ADR-0006: pykit verifies tokens an authorization server issued and never issues its own; browsers hold a session, not a token
Status: accepted (2026-10-26) · Scope: authentication across all
rn-forge-* packages
Decision
pykit is an OIDC relying party, never an authorization server or a SAML service provider.
- Tokens come from an authorization server. An IdP or broker issues every
token. pykit verifies the tokens its APIs accept and maps them to a
Principalunder the shared 401/403 contract. It mints no token of its own, including a short-lived one after a login. - Browsers hold a session. A browser authenticates with a server-side session behind an HttpOnly cookie. The backend is the browser's only party to the protocol (the backend-for-frontend pattern), and tokens, assertions and secrets stay on the server.
- The locally issued JWT flows are removed, not kept beside the session.
- SAML goes through a broker. A SAML IdP federates through a broker that speaks OIDC to the app; pykit carries no SAML code.
Consequences
- Machine clients, native apps and several APIs need a broker that issues tokens. pykit does not become one when a second client appears.
- Every application serves its SPA and API from one origin or one site, and protects unsafe methods with CSRF checks, because a cookie is sent automatically.
- Revocation, "sign out everywhere" and back-channel logout take effect on the next request, at the cost of server-side session storage shared by every worker.
- An IdP that offers only SAML needs a broker. pykit carries no XML-signature
code and no native
xmlsec1dependency. rn-forge-djangoloses itsjwtandsamlextras and the views behind them, a breaking release (F13.7).
Influences
E13's design: its sessions and cookies, token validation and what this replaces, and F13.7, which does the removal.
Alternatives considered
-
Authorization-code and PKCE flows that end in a pykit-issued token. Every application becomes an unaudited authorization server with its own key management, revocation and replay concerns. The existing exchange token is also a valid SimpleJWT refresh token, redeemable at SimpleJWT's refresh endpoint.
-
The SPA as a public OAuth client, holding tokens in memory. Script in the page can still acquire new tokens, revocation waits for expiry, and social login would always need a broker. The design's browser-client alternative compares the two.
-
A token-mediating backend. It still puts an access token within reach of script, and adds the backend login flow as well.
-
A SAML service provider in pykit (python3-saml). It brings XML-signature handling and
xmlsec1, and python3-saml has had no release since 2023-10. Every major workforce IdP also speaks OIDC, and a broker serves the rest.
Background
Stated in the cross-package auth overview written on 2026-09-13 and recorded here 2026-09-25. Revised on 2026-10-27 to add the browser session and the removal of the locally issued JWT flows, which the owner accepted with E13's design on 2026-10-26. Revised again on 2026-10-27 to move SAML to a broker (S13.1.5), after the library evaluation found python3-saml unreleased since 2023-10.