Skip to content

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 Principal under 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 xmlsec1 dependency.
  • rn-forge-django loses its jwt and saml extras 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.