Skip to content

F13.5 — Django binding

State Closed
Parent E13
Iteration Release 7
Start Date 2026-10-28
Closed Date 2026-10-28
Predecessors F13.4
Source Owner decision, 2026-10-26

Stories: 7 Closed

Story State Depends on
S13.5.1 — Routes Closed (2026-10-28) —
S13.5.2 — Sessions and revocation Closed (2026-10-28) —
S13.5.3 — CSRF Closed (2026-10-28) —
S13.5.4 — Account resolution and authentication Closed (2026-10-28) —
S13.5.5 — Authorization Closed (2026-10-28) —
S13.5.6 — Rate limiting and audit events Closed (2026-10-28) —
S13.5.7 — Document the binding Closed (2026-10-28) —

rn-forge-django binds the shared HTTP surface, sessions, CSRF and authorization over rn-forge-auth, as Package responsibilities lists for it.

Context

Libraries binds Django's own sessions, CSRF middleware, auth models and Redis cache backend, and pykit's adapters for every login flow; django-allauth is not bound, because it does not link on (issuer, subject). ADR-0014 requires the same surface and defaults as F13.6. Every security control has a test in this package.

Decisions

  • Owner decision, 2026-10-28: mounting the auth surface without a problem type_base is a configuration error, so csrf-failed and forbidden differ in type (E13).
  • Owner decision, 2026-10-28: the Redis cache backend's client comes from rn-forge-auth's existing redis extra; rn-forge-django gains a redis extra on rn-forge-auth[redis] rather than declaring redis itself.
  • Owner decision, 2026-10-28: rate limiting is the binding's own, a fixed-window counter over Django's cache, answering 429. rn-forge-auth gains no limiter; F13.6 writes its own.
  • Owner decision, 2026-10-28: the new code lives in the existing rn_forge.django.auth app beside the legacy flows F13.7 removes, and the link model's migration is that app's.

S13.5.1 — Routes

State: Closed (2026-10-28)

Acceptance:

  • Views and a URLconf serve every route of HTTP surface under a configurable prefix, with the responses the table lists.
  • Provider configuration is built from rn-forge-auth's types and passed to the binding; the settings facade has no AUTH.OIDC block.
  • Login transactions and replay records live in Django's Redis cache, behind the __Host-login-tx cookie with the flags of Sessions and cookies. A callback carrying more than one transaction cookie is rejected.
  • Callback errors redirect to the configured error route with one code from the closed list. No Location header, URL or log record in the route tests contains a token, code or assertion.
  • /auth/login/development exists only in debug mode.

S13.5.2 — Sessions and revocation

State: Closed (2026-10-28)

Acceptance:

  • Sessions use django.contrib.sessions with the db or cached_db backend, in the __Host-session cookie with the design's flags, and hold only the session content the design lists.
  • Tests show a 30-minute sliding idle timeout, a 12-hour absolute timeout, GET /auth/session not extending the session, and a new session ID at login and on privilege change.
  • A session whose recorded version no longer matches its account's, or whose session_ref is revoked, is deleted on read and answered 401.
  • /auth/logout, /auth/logout/all and back-channel logout end the sessions Revocation says they do.
  • Race tests run concurrent requests against a logout, a back-channel logout and an account disablement, and no request after the revocation succeeds.
  • Outside debug mode the binding refuses a signed-cookie session backend and Django's local-memory cache.

S13.5.3 — CSRF

State: Closed (2026-10-28)

Acceptance:

  • CsrfViewMiddleware protects every unsafe method on a session-authenticated route, with cookie and header names matching Angular's XSRF support. /auth/session always sets the CSRF cookie.
  • CSRF_FAILURE_VIEW returns the 403 csrf-failed problem, and the conformance case for it passes: the driver's PROVIDES set in tests/test_conformance.py gains session-routes and csrf, so the session-only 401 and csrf-failed cases run.
  • Mounting the auth surface without a problem type_base raises ImproperlyConfigured.
  • Tests show the origin check rejecting an untrusted Origin or Referer and Sec-Fetch-Site: cross-site, and trusting forwarded headers only from a configured proxy.
  • Back-channel logout and bearer-authenticated requests are exempt. /auth/login/password is protected before sign-in, and the CSRF token rotates at login and logout.

S13.5.4 — Account resolution and authentication

State: Closed (2026-10-28)

Acceptance:

  • A default AccountResolver on the Django user model and an external-account link model unique on (issuer, subject), with its migration, implement Account linking: the existing, jit and domain-allowlisted jit policies, email linking only when verified and the provider is authoritative for the domain, an attribute-sync hook and service-account links.
  • A rejected login redirects with account_not_provisioned.
  • A DRF authentication class yields a session Principal. PrincipalBearerAuthentication and JWKSBearerAuthentication resolve the token's (issuer, subject) through AccountResolver.lookup, never provision, and answer 401 for an unlinked subject.
  • A request with an Authorization header is authenticated by the bearer path alone: an invalid token is 401 even with a valid session cookie.

S13.5.5 — Authorization

State: Closed (2026-10-28)

Acceptance:

  • A default AuthorizationContextProvider builds permission keys from Django groups and permissions. Staff and superuser bypass is a role that grants every permission and shows in /auth/session.
  • Changes through the User, Group and Permission viewsets, and the model signals behind them, bump the affected authorization versions.
  • A DRF permission class checks a Requirement built by the action-to-key helper. ResourcePolicy hooks check objects (404 when existence is sensitive) and scope list querysets, with tests for pagination over a scoped list.

S13.5.6 — Rate limiting and audit events

State: Closed (2026-10-28)

Acceptance:

  • /auth/login/password and the callback endpoints are rate-limited per account and per client, with configurable limits, in tests. A limited request is answered 429, with Retry-After.
  • Login success and failure, logout, account provisioned, rejected or disabled, and authorization denied each emit an event on the AppLogger audit channel, in tests.

S13.5.7 — Document the binding

State: Closed (2026-10-28)

Acceptance:

  • The Django auth guide describes the new surface, configuration and defaults.
  • The changelog records the binding. Both strict MkDocs builds pass.

Acceptance

  • The HTTP surface is served from views with provider configuration from rn-forge-auth (S13.5.1).
  • Sessions time out, rotate and revoke as designed, and the race tests pass (S13.5.2).
  • CSRF and the origin check protect unsafe methods (S13.5.3).
  • Session and bearer callers resolve to accounts through the link model (S13.5.4).
  • The default context provider, DRF permissions and resource policies authorize (S13.5.5).
  • Rate limits and audit events are in place (S13.5.6).
  • The binding is documented (S13.5.7).
uv run --package rn-forge-django pytest packages/rn-forge-django
uv run pyright
sh docs/_update_board.sh --check