Auth
rn_forge.django.auth binds the login, session, CSRF and authorization design
of rn-forge-auth (a separate package, which holds the framework-neutral
contracts, login flows and OIDC adapter) to Django and DRF. It serves a browser
single-page application through a server-side session, and API clients through
bearer tokens, with one account and one authorization model behind both.
The app is installable (label rn_forge_django_auth).
Setup
An end-to-end configuration with one OIDC provider, local password login and, in
development, a fixture-account provider. Install rn-forge-django with the
drf, oidc and redis extras.
Settings:
# settings.py
from rn_forge.django.auth import CSRF_MIDDLEWARE, CSRF_SETTINGS, SESSION_SETTINGS
INSTALLED_APPS = [
"django.contrib.auth",
"django.contrib.contenttypes",
"django.contrib.sessions",
"rest_framework",
"rn_forge.django.auth", # run `manage.py migrate` for the link and state tables
"myapp",
]
MIDDLEWARE = [
"django.middleware.security.SecurityMiddleware",
"django.contrib.sessions.middleware.SessionMiddleware",
# ... your other middleware ...
CSRF_MIDDLEWARE,
]
globals().update(SESSION_SETTINGS) # db-backed sessions, the __Host-session cookie
globals().update(CSRF_SETTINGS) # Angular's XSRF-TOKEN cookie and X-XSRF-TOKEN header
CACHES = {
"default": {
"BACKEND": "django.core.cache.backends.redis.RedisCache",
"LOCATION": "redis://localhost:6379/1",
}
}
RN_FORGE_DJANGO = {"AUTH": {"PROBLEM_TYPE_BASE": "https://errors.example.com/"}}
REST_FRAMEWORK = {
"EXCEPTION_HANDLER": "rn_forge.django.drf.exceptions.problem_details_exception_handler",
}
LogoutTokenVerifier.from_issuer reads the provider's discovery document when
it is called, so the provider must be reachable at startup.
The Redis cache backend holds login transactions, replay records and revoked
session IDs, which every worker must share; the redis extra installs its
client. The session cookie is Secure, so serve development over localhost or
HTTPS.
The auth objects, built once:
# myapp/auth_config.py
from django.conf import settings
from django.contrib.auth import authenticate
from rn_forge.auth import (
AuthorizationContextCache,
DevelopmentAccount,
DevelopmentIdentityProvider,
PasswordIdentityProvider,
)
from rn_forge.auth.oidc import BackchannelLogout, LogoutTokenVerifier, OidcProvider
from rn_forge.django.auth import AuthRoutesConfig, CacheReplayStore
from rn_forge.django.auth.accounts import (
DjangoAccountResolver,
DjangoAccountStateWriter,
ProviderPolicy,
)
from rn_forge.django.auth.authorization import DjangoAuthorizationContextProvider
from rn_forge.django.auth.drf import PrincipalSessionAuthentication, sessions_for
from rn_forge.django.auth.drf.oidc import JWKSBearerAuthentication
ISSUER = "https://login.example.com/tenant/v2.0"
def verify_password(username: str, password: str) -> str | None:
user = authenticate(username=username, password=password)
return str(user.pk) if user else None
replay = CacheReplayStore()
resolver = DjangoAccountResolver(
{
"acme": ProviderPolicy(
provisioning="jit",
email_domains=frozenset({"example.com"}),
authoritative_domains=frozenset({"example.com"}),
),
# A local user is linked once: resolver.link("local", str(user.pk), user)
"password": ProviderPolicy(),
"development": ProviderPolicy(provisioning="jit"),
}
)
contexts = AuthorizationContextCache(
DjangoAuthorizationContextProvider(), writer=DjangoAccountStateWriter()
)
providers = {
"acme": OidcProvider(
id="acme",
issuer=ISSUER,
client_id="orders-web",
client_secret="...",
redirect_uri="https://app.example.com/auth/callback/acme",
),
"password": PasswordIdentityProvider(verify_password),
}
if settings.DEBUG:
providers["development"] = DevelopmentIdentityProvider(
[DevelopmentAccount("alice", name="Alice")], debug=True
)
config = AuthRoutesConfig(
providers=providers,
accounts=resolver,
contexts=contexts,
account_state=contexts, # writes through to DjangoAccountStateWriter
return_to_prefixes=["/app"],
default_return_to="/app",
provider_names={"acme": "Acme SSO", "password": "Password"},
replay=replay,
backchannel={
"acme": BackchannelLogout(
LogoutTokenVerifier.from_issuer(
ISSUER, client_id="orders-web", replay_store=replay
),
resolver,
)
},
)
class Session(PrincipalSessionAuthentication):
sessions = sessions_for(config)
class Bearer(JWKSBearerAuthentication):
jwks_url = "https://login.example.com/tenant/discovery/v2.0/keys"
issuer = ISSUER
audience = "api://orders"
accounts = resolver
contexts = contexts
A view lists the classes it accepts:
# myapp/api/views.py
from rest_framework.views import APIView
from myapp.auth_config import Bearer, Session
class OrderView(APIView):
authentication_classes = [Session, Bearer]
The URLconf and the authorization signals:
# myapp/urls.py
from django.urls import include, path
from rn_forge.django.auth import auth_urlpatterns
from myapp.auth_config import config
urlpatterns = [
*auth_urlpatterns(config, prefix="auth"),
path("api/", include("myapp.api.urls")),
]
# myapp/apps.py
from django.apps import AppConfig
class MyAppConfig(AppConfig):
name = "myapp"
def ready(self) -> None:
from rn_forge.django.auth.authorization import connect_authorization_signals
from myapp.auth_config import contexts
connect_authorization_signals(contexts)
auth_urlpatterns checks the session, CSRF and cache settings when it builds
the URLconf and raises ImproperlyConfigured for a configuration it refuses
(Defaults and startup checks).
Routes and responses
auth_urlpatterns(config, prefix="auth") serves these routes under the prefix.
The URL names are rn-forge-auth-<route>. A 401 from any of them is a
problem+json response with no WWW-Authenticate header.
| Method | Path | Response |
|---|---|---|
GET |
providers |
200, a list of {id, name, kind}. kind is oidc, oauth2, password or development; the development provider is listed only in DEBUG |
GET |
login/{provider}?return_to= |
302 to the identity provider, with the __Host-login-tx cookie. A return_to outside return_to_prefixes redirects to the error route. An unknown provider is 404 |
GET |
login/development?account= |
In DEBUG only (otherwise 404): without account, an HTML list of the fixture accounts; with it, signs in and redirects to return_to |
GET |
callback/{provider} |
302 to return_to, or to the error route; 429 when rate limited |
GET |
session |
200 with the session body, or 401. Always sets the CSRF cookie |
POST |
logout |
200 {"redirect": url or null}; 401 without a session |
POST |
logout/all |
200 {"redirect": null}; 401 without a session |
POST |
backchannel-logout/{provider} |
200; 400 for an invalid logout token; 404 for a provider with no handler |
POST |
login/password |
200 with the session body, 401 for any failure, or 429 |
A callback error redirects to error_route (/auth/error) with ?error= set
to one of access_denied, account_not_provisioned and login_failed. Details
go to the log, never into the URL. A password login failure is one 401
whatever its cause, so the response does not reveal which accounts exist. The
login body is JSON or form-encoded {username, password}.
The session body is camelCase: subject (the account ID), provider, roles,
permissions, attributes, authTime, amr and expiresAt (the absolute
timeout). It omits name, email and picture: the default resolver stores
none. Cache-Control: no-store is set on session responses.
The login transaction lives in the cache for 10 minutes behind the
__Host-login-tx cookie (HttpOnly, Secure, SameSite=Lax, Path=/, no
Domain). A callback that carries more than one transaction cookie is rejected,
and a transaction is consumed atomically, so a callback works once.
Sessions and revocation
Sessions are django.contrib.sessions with the db or cached_db engine, in
the __Host-session cookie (HttpOnly, Secure, SameSite=Lax, Path=/, no
Domain). The session holds the account ID, the account's session version at
login, provider, issuer, external subject, auth_time, amr, session_ref and
the ID token (only with rp_initiated_logout), and never permissions: those are
computed on each request.
- Timeouts. A 30-minute sliding idle timeout (
idle_timeout) and a 12-hour absolute timeout (absolute_timeout). A normal read moves the idle expiry forward;GET /auth/sessionreads withtouch=Falseand does not. - One read path.
Sessions.readdeletes the session, and the caller answers401, when the absolute timeout has passed, the recorded session version differs from the account's, the account is inactive, or thesession_refis revoked. - New IDs. Login gives the session a new ID. Call
rotate_session(request)after a change to the account's privileges. - Logout.
/auth/logoutends the current session./auth/logout/alland a back-channel logout that names onlysubbump the account's session version, which ends every session of the account on its next request. A back-channel logout with asidrevokes that session only, until the absolute timeout. Withrp_initiated_logouton the provider,/auth/logoutreturns the identity provider's end-session URL. - Disabling.
contexts.set_active(account_id, False)(or any change that makes the account inactive) fails the account's next request with401.
The authorization context cache is local to each process: a change made in
another process applies after the cache's ttl (60 seconds by default), or at
once through the cache that made it. Lower ttl where that delay matters.
CSRF
Every unsafe method on a session-authenticated route is protected by
AuthCsrfMiddleware, a CsrfViewMiddleware subclass. The cookie is
XSRF-TOKEN and the header X-XSRF-TOKEN, Angular's defaults; the cookie is
not HttpOnly so that Angular can copy it into the header.
GET /auth/sessionalways sets the cookie, including when it answers401, soPOST /auth/login/passwordis protected before sign-in. The token rotates at login and at logout.- A rejection is the
403csrf-failedproblem (CSRF_FAILURE_VIEW); its reason is logged, never sent.PROBLEM_TYPE_BASEmakes it differ intypefrom a permission denial. - Beyond Django's token and origin check,
AuthCsrfMiddlewarerejectsSec-Fetch-Site: cross-siteon an unsafe method, even from a trusted origin. - Requests with a
BearerAuthorizationheader skip the check, as does the back-channel logout route, which carries a signed token. ABasicheader does not: browsers replay cached Basic credentials on their own. CSRF_TRUSTED_ORIGINSlists the other origins that may post. Behind a proxy, Django takes the request's scheme and host from forwarded headers only whenSECURE_PROXY_SSL_HEADERandUSE_X_FORWARDED_HOSTare set, and the forwarded host must be inALLOWED_HOSTS. Without them a forgedX-Forwarded-*header does not make a foreignOriginacceptable.- DRF wraps its views in
csrf_exempt, so the middleware does not guard them.PrincipalSessionAuthenticationcallsenforce_csrf(request)for the sessions it authenticates; a custom session class does the same.
Accounts and linking
DjangoAccountResolver links external identities to Django users through the
ExternalAccount model, unique on (issuer, subject); run the auth app's
migration. A ProviderPolicy per provider ID decides what an unlinked identity
gets; a provider with no policy is rejected.
provisioning="existing"rejects an identity with no account;provisioning="jit"creates one on first login, limited toemail_domainswhen set (which also requires a verified email).authoritative_domainslists the email domains for which the provider is authoritative: only there does a verified email link to an existing user. Unverified emails never link and are not stored on provisioned users.sync(user, identity), passed to the resolver, runs at every login to copy attributes onto the user.resolver.link(issuer, subject, user)links a service account or a local password user explicitly.
A rejected login redirects with ?error=account_not_provisioned, and a login by
an inactive account with ?error=access_denied. The session version behind
/auth/logout/all is stored by DjangoAccountStateWriter and read by
DjangoAuthorizationContextProvider.
Authentication
PrincipalSessionAuthentication yields a Principal with mechanism="session"
from Sessions.read; request.auth is the SessionInfo. Subclass it and set
sessions = sessions_for(config).
PrincipalBearerAuthentication and JWKSBearerAuthentication verify an
externally issued token, then resolve its (issuer, subject) through
AccountResolver.lookup. They never provision: an unlinked subject, or an
inactive account, is 401. The principal's subject is the account ID; its
roles and attributes come from the authorization context, and its permissions
are the account's, limited to what the token's scopes allow through scope_map:
class Bearer(JWKSBearerAuthentication):
...
scope_map = {"orders:read": frozenset({"orders.list", "orders.read"})}
List the classes on each view or on a shared base view, not in
DEFAULT_AUTHENTICATION_CLASSES: that setting is imported while DRF imports its
views, and the module that defines these classes imports DRF's views too.
One credential per request. A request with an Authorization header is
authenticated by the bearer class alone: an invalid token is 401 even with a
valid session cookie, and the session class ignores the request. List the
classes a view accepts. A view whose first class is the session class answers an
unauthenticated request with 401 and no WWW-Authenticate header; with a
bearer class first, it answers with the Bearer challenge. Both need the
problem-details exception handler.
Bearer tokens in detail
For an API whose callers hold tokens issued by an identity provider (Entra ID,
Auth0, Okta, Keycloak), JWKSBearerAuthentication (the oidc extra) verifies
the token against the provider's key set. Set jwks_url, issuer, audience,
accounts and contexts on a subclass, as in Setup. cache_timeout
(300 seconds) is how long a fetched key set is kept, cooldown_duration (30
seconds) the fewest seconds between two fetches, which bounds how often an
unknown kid can reach the provider, and algorithms and leeway set the
accepted algorithms and the clock skew. Override claims_to_principal() where
the provider keeps roles or scopes somewhere non-standard, such as Keycloak's
nested realm_access.roles. The authenticator and key set are cached per
subclass and process, so define the class once.
| Provider | jwks_url |
|---|---|
| Entra ID | https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys |
| Auth0 | https://{domain}/.well-known/jwks.json |
| Okta | https://{domain}/oauth2/{authorization-server-id}/v1/keys |
To verify tokens some other way, subclass PrincipalBearerAuthentication and
set authenticator to any rn_forge.auth.Authenticator, with accounts,
contexts and optionally realm. Protect a view with
requires(Requirement(all_scopes=...)), a permission class over the principal's
scopes and roles, which evaluates identically on rn-forge-fastapi:
from rest_framework.views import APIView
from rn_forge.auth import Requirement
from rn_forge.django.auth.drf import requires
class OrderView(APIView):
authentication_classes = [Bearer]
permission_classes = [requires(Requirement(all_scopes=frozenset({"orders:read"})))]
With problem_details_exception_handler installed, missing or invalid
credentials are a 401 problem+json with an RFC 6750
WWW-Authenticate: Bearer challenge and a detail that never says why
verification failed; valid credentials lacking the scope are a 403 with no
challenge.
PrincipalBasicAuthentication is the RFC 7617 twin: it produces a Principal
from an authenticator you supply and does not link accounts. It is for local
development and simple internal deployments only.
Authorization
DjangoAuthorizationContextProvider builds an AuthorizationContext from a
user's groups and permissions. Roles are group names. Django
app_label.codename permissions become dotted keys: add, change, delete
and view of a model map to <app_label>.<model>.create, update, delete
and read (view also grants list), so inventory.change_stock is
inventory.stock.update. A custom permission keeps <app_label>.<codename>. A
staff or superuser account gets the staff or superuser role and every
permission key, so the bypass shows in /auth/session; pass catalog= for keys
that exist outside Django's permission table. An unknown or inactive user
resolves to an inactive context.
Wrap the provider in an AuthorizationContextCache and call
connect_authorization_signals(cache) once at startup (Setup):
changes to users, groups, permissions and their relations, including those made
through the User, Group and Permission viewsets, then invalidate the
affected accounts.
On a view, PermissionKeyPermission requires the key built by
rn_forge.auth.requirement_for from permission_key and the action, checked
against the request's principal; a view without a permission_key requires only
an authenticated principal. ResourcePolicyViewMixin applies a
ResourcePolicy: scope narrows the queryset, so counts and pages cover only
permitted rows, and allows guards each object, answering 404 instead of
403 when policy_hides_existence is true. Both are in
rn_forge.django.auth.drf.
from rn_forge.django.auth.drf import PermissionKeyPermission, ResourcePolicyViewMixin
class OrderViewSet(ResourcePolicyViewMixin, ModelViewSet):
permission_classes = [PermissionKeyPermission]
permission_key = "orders"
resource_policy = OrderPolicy()
Management viewsets
rn_forge.django.auth.drf.views ships ready-to-mount viewsets for the standard
Django auth models, wired through AuthorizedModelViewSet: PermissionViewSet,
GroupViewSet, UserViewSet. AuthorizedModelViewSet and AuthorizedAPIView
set permission_classes = [PermissionKeyPermission], so each viewset requires
its permission_key (rn_forge.auth.permission, rn_forge.auth.group,
rn_forge.auth.user) combined with the action. Mount them, or
rn_forge.django.auth.urls.urlpatterns, which already registers them, under
your API root.
Rate limits and audit events
POST /auth/login/password and GET /auth/callback/{provider} are rate limited
with a fixed-window counter over Django's cache (cache.add and cache.incr),
in the cache alias of AuthRoutesConfig.limiter (FixedWindowLimiter). The
client is REMOTE_ADDR: Django resolves proxies through its own settings, and
X-Forwarded-For is never read here. Password login is limited per client and
per submitted username (hashed in the key); callbacks per client only, because
no account is known before the response is verified. Each limit is a
RateLimit(limit, window), or None for none. A limited request is the 429
too-many-requests problem with Retry-After. Windows are aligned to the
clock, so a client can use a limit twice around a window boundary.
Security-relevant events are INFO records on the rn_forge.audit.auth
AppLogger channel, in the form audit event=<name> key='value' ...:
| Event | Emitted when |
|---|---|
login.success |
A login starts a session |
login.failure |
A login fails (provider, code, reason) |
logout, logout.all, logout.backchannel |
A session or sessions end |
account.provisioned |
The resolver creates an account (after commit) |
account.rejected |
The resolver refuses an identity |
account.disabled |
An inactive account logs in, or DjangoAccountStateWriter.set_active(False) runs |
authorization.denied |
PermissionKeyPermission or ResourcePolicyViewMixin denies a request |
rate_limited |
A request is answered 429 |
Events carry account IDs, provider IDs, codes and short reasons, and never a token, code, assertion, password, session ID or email address.
Defaults and startup checks
Configured on AuthRoutesConfig unless noted:
| Setting | Default |
|---|---|
URL prefix (auth_urlpatterns(prefix=)) |
auth |
return_to_prefixes / default_return_to |
("/",) / / |
error_route |
/auth/error |
post_logout_redirect |
/ |
idle_timeout / absolute_timeout |
30 minutes / 12 hours |
| Login transaction lifetime | 10 minutes |
password_client_limit |
30 per 5 minutes |
password_account_limit |
10 per 5 minutes |
callback_client_limit |
60 per 5 minutes |
transactions, replay, limiter |
Django's default cache |
| Session cookie | __Host-session, HttpOnly, Secure, SameSite=Lax, Path=/, no Domain |
| Login transaction cookie | __Host-login-tx, same flags, Max-Age=600 |
| CSRF cookie / header | XSRF-TOKEN (not HttpOnly, Secure, SameSite=Lax, Path=/) / X-XSRF-TOKEN |
Authorization cache ttl |
60 seconds |
auth_urlpatterns raises ImproperlyConfigured when it builds the URLconf:
| Refused | Always | Outside DEBUG |
|---|---|---|
SESSION_SAVE_EVERY_REQUEST true |
yes | yes |
AuthCsrfMiddleware missing from MIDDLEWARE |
yes | yes |
CSRF cookie and header names, HttpOnly, CSRF_USE_SESSIONS, CSRF_FAILURE_VIEW differing from CSRF_SETTINGS |
yes | yes |
RN_FORGE_DJANGO["AUTH"]["PROBLEM_TYPE_BASE"] unset |
yes | yes |
Session cookie settings differing from SESSION_SETTINGS |
no | yes |
Other CSRF cookie settings differing from CSRF_SETTINGS |
no | yes |
A session engine other than db or cached_db (the signed-cookie engine cannot revoke sessions) |
no | yes |
| Django's local-memory cache as the session cache, or for the transaction, replay or limiter store | no | yes |
/auth/login/development and the development provider's listing exist only
while settings.DEBUG is true.
SAML identity providers
rn-forge-django speaks no SAML. A SAML identity provider federates through a
broker (Keycloak, Entra ID, Auth0, Okta and others) that runs the SAML exchange
and logs the user in to the application over OIDC; configure the broker as an
ordinary OidcProvider. The rn-forge-auth login guide, "Connecting a SAML IdP
through a broker", has the steps.