E13 — Auth patterns
| Epic | E13 |
| Settled by | F13.1 |
A reference to the industry-standard authentication, session and token, and authorization patterns, written so the owner can review the design against the field. It describes the patterns and their trade-offs, then marks each one's status in this design. A status records the design's position; the design's proposed decisions become ADRs through F13.1.
Status vocabulary used in the tables:
| Status | Meaning |
|---|---|
| Adapter | The design proposes a pykit adapter for it. |
| Via broker | The app speaks OIDC to a broker, and the broker handles it. |
| Custom | Possible through a custom authenticator or provider; pykit ships nothing. |
| Out of scope | Not in this design. |
The three layers
Auth is three separate jobs. Treating them separately is what lets an app mix, for example, SAML login with cookie sessions and a policy-engine check.
flowchart LR
A["1. Authentication<br/>prove who the caller is"] -- "ExternalIdentity" --> S["2. Session and token management<br/>carry that identity on later requests"]
S -- "Principal" --> Z["3. Authorization<br/>decide what the caller may do"]
Z --> D["allow or deny"]
| Layer | Input | Output | Contract in design.md | Example choices |
|---|---|---|---|---|
| Authentication | Credentials, or a protocol response | ExternalIdentity: issuer, subject, claims, auth_time, amr, session_ref |
IdentityProvider, then AccountResolver (Contracts) |
OIDC, SAML, social login, passwords, passkeys, client credentials |
| Session and token management | A proven identity (an account ID, or a client ID) | A verified caller identity on every later request, as a Principal |
The framework session binding, and Authenticator for bearer tokens |
Server session with a cookie, JWT access token, opaque token, refresh token |
| Authorization | Principal, an action, a resource |
Allow or deny; a filtered query | AuthorizationContextProvider, Requirement, ResourcePolicy |
RBAC, ABAC, ReBAC, ACLs, policy engines |
Each layer meets the next through one contract. An authentication method never needs to know how the identity will travel, and an authorization model never needs to know how the caller authenticated. The few legitimate exceptions are listed under Independence rules.
Common confusions:
- OAuth 2.0 is delegated authorization, not authentication. An access token says a client may call an API on someone's behalf. It does not say who is at the keyboard. OpenID Connect adds the ID token and the login semantics.
- A scope is not a permission. A scope limits what a token may do. A permission is what the application grants a user. A delegated call is allowed only when both agree.
- JWT is a token format, not a session strategy. A JWT can be an access token, an ID token or a logout token. Whether it is the thing a browser holds across requests is a separate choice.
- SSO is an outcome, not a protocol. The user signs in once and reaches several apps. OIDC and SAML are the two common protocols that deliver it.
- Authentication is not account lookup. Proving a subject at an IdP does not say which application account it maps to. That is account resolution.
Authentication patterns
OpenID Connect: authorization code with PKCE
- What: OIDC Core 1.0 layers an identity protocol over OAuth 2.0 (RFC 6749). The app (relying party) sends the user to the provider and gets back a signed ID token.
- Flow: redirect with
state,nonceand a PKCE challenge (RFC 7636); user authenticates at the provider; redirect back with a code; the backend exchanges the code at the token endpoint; it verifies the ID token (signature from the provider's JWKS,iss,aud,exp,nonce); optionally it callsuserinfo. - Use when: the provider speaks OIDC. This is the default choice for new work.
- Pitfalls: skipping
stateornoncechecks; accepting an ID token without checkingaud; the implicit and password grants (removed by RFC 9700, OAuth 2.0 Security Best Current Practice); open redirects through an unvalidated return URL; mix-up attacks, which theissresponse parameter (RFC 9207) closes. - Status: Adapter. See OIDC login.
sequenceDiagram
participant U as User agent
participant RP as App backend
participant OP as OIDC provider
U->>RP: start login
RP-->>U: redirect with state, nonce, PKCE challenge
U->>OP: authenticate
OP-->>U: redirect back with code
U->>RP: callback with code
RP->>OP: code + PKCE verifier
OP-->>RP: ID token
RP->>RP: verify, map to ExternalIdentity
OAuth 2.0 social login without OIDC
- What: Some providers (GitHub is the usual example) issue an access token but no ID token. The app calls the provider's user endpoint with that token to learn who the user is.
- Flow: the same authorization code flow, then
GETthe provider's user API. - Use when: the provider offers nothing better.
- Pitfalls: no signed identity assertion, so the identity is only as trustworthy as the TLS call to the provider; emails may be unverified or have to be fetched from a second endpoint; linking accounts on email is an account-takeover path.
- Status: Adapter ("OAuth 2.0 + userinfo" in Deployment profiles), or Via broker.
SAML 2.0
- What: An XML-based protocol (OASIS SAML 2.0) common in enterprise SSO. The IdP posts a signed assertion to the app's Assertion Consumer Service.
- SP-initiated flow: the app sends an
AuthnRequestwith a fresh ID; the IdP authenticates the user and posts aSAMLResponsewhoseInResponseTomatches that ID. The app validates the signature,Destination,Audienceand time conditions, and records the assertion ID to stop replay. - IdP-initiated flow: the user starts from the IdP's portal and the IdP
posts an unsolicited response. It has no
InResponseTo, so the app cannot tell a response it asked for from one an attacker induced (login CSRF), and the replay cache becomes the only defense. Use it only when a customer insists, per provider. - Use when: a customer or corporate IdP offers only SAML.
- Pitfalls: XML signature wrapping (use a maintained library, require signed
assertions, strict mode); trusting
RelayStateas a URL; linking on email instead of a persistent NameID; certificate rollover. - Status: Via broker. pykit speaks no SAML; see SAML identity providers.
The broker pattern
- What: One OIDC-speaking service (Keycloak, Entra ID, Auth0, Zitadel, Authentik, Okta) sits between the app and every upstream IdP. The app speaks one protocol; the broker speaks SAML, social, LDAP and others, and issues the tokens.
- Use when: more than one app or API, machine clients, native apps, or many customer IdPs.
- Pitfalls: one more service to run or pay for; the broker's claim shapes
and logout behavior leak into the app unless mapped to
ExternalIdentityat the edge. - Status: Via broker. This is the "broker profile" of Deployment profiles, recommended.
Local passwords
- What: The app stores a password verifier and checks it at login.
- Rules (NIST SP 800-63B): length over complexity (at least 8, allow at least 64 characters); no composition rules and no periodic rotation; check candidates against a breached-password list; allow paste and password managers; store with a memory-hard hash such as argon2id; rate-limit per account and per client; do not reveal whether the account exists (OWASP Password Storage and Authentication cheat sheets).
- Use when: there is no IdP, or for break-glass administrator accounts.
- Pitfalls: every app becomes a credential store with a breach liability; recovery and enrollment flows are large attack surfaces.
- Status: Adapter (optional provider). Registration, reset and recovery are out of scope (Goals and non-goals).
Passkeys and WebAuthn
- What: Public-key credentials bound to the origin (W3C WebAuthn, FIDO2). The private key stays on the user's device or password manager; the server stores a public key and verifies a signed challenge.
- Use when: you want phishing-resistant login without passwords. NIST 800-63B lists such authenticators at the highest assurance.
- Pitfalls: enrollment, recovery and device-loss flows are the hard part, not verification; relying-party ID must match the origin.
- Status: Via broker (the IdP offers passkeys, the app sees a normal OIDC login). No local adapter.
Magic links and email one-time codes
- What: The app emails a single-use link or code; possession of the mailbox is the proof.
- Use when: low-risk consumer apps where passwords are unwanted.
- Pitfalls: security equals the mailbox's; link scanners consume single-use links; codes need attempt limits; the link must be bound to the browser that asked for it.
- Status: Out of scope for the first version.
Multi-factor and step-up authentication
- What: MFA combines factors (knowledge, possession, inherence). Step-up asks for a stronger or fresher authentication before a sensitive action.
- How it is signaled: OIDC carries
acr(the assurance level reached),amr(the methods used, RFC 8176:pwd,otp,hwk,mfa) andauth_time. A relying party can request a level withacr_valuesand a freshness limit withmax_age. RFC 9470 defines the same for OAuth APIs. - Pitfalls: treating a claim as proof without checking
issandaud; checking MFA only at login and never at the sensitive action. - Status: The IdP runs MFA. The design records
auth_timeandamrand defers theRequirementclause (Authorization model).
Machine authentication
| Method | How it works | Notes | Status |
|---|---|---|---|
| Client credentials (RFC 6749 §4.4) | The client authenticates to the token endpoint with a secret and gets an access token | Simplest standard option; the secret must be stored and rotated | Via broker |
private_key_jwt (RFC 7523, OIDC Core §9) |
The client signs a JWT assertion with its private key | No shared secret to leak | Via broker |
| Mutual TLS (RFC 8705) | Client authenticates with a certificate; tokens can be bound to it | Needs PKI and TLS termination that passes the certificate | Via broker; verifying the binding is out of scope |
| API keys | A long random string the server looks up | Not a standard protocol; no expiry, scope or audience unless built in; store only a hash | Custom |
Authentication comparison
| Pattern | Standard | Strength | Main cost | Status |
|---|---|---|---|---|
| OIDC code + PKCE | OIDC Core, RFC 6749, RFC 7636 | Signed identity, mature libraries | Needs an OIDC provider | Adapter |
| OAuth 2.0 social login | RFC 6749 | Reaches providers without OIDC | Unsigned identity, email caveats | Adapter or broker |
| SAML 2.0 | OASIS SAML 2.0 | Universal in enterprise | XML signature risks, no native mobile story | Via broker |
| Broker | OIDC upstream, any downstream | One protocol in the app | A service to run | Recommended profile |
| Local password | NIST 800-63B | No external dependency | Credential liability | Adapter, optional |
| Passkey | WebAuthn | Phishing-resistant | Enrollment and recovery | Via broker |
| Magic link | None | No password | Mailbox is the factor | Out of scope |
| Client credentials | RFC 6749 | Standard for services | Secret handling | Via broker |
| API key | None | Easy for integrators | Weak by default | Custom |
Session and token patterns
After authentication, something must tell the server who is calling on each later request. The choice depends on who the caller is (a browser, a native app, a service) more than on how it logged in.
Server-side session with a cookie
- What: The server stores session state and gives the browser an opaque ID in a cookie (OWASP Session Management cheat sheet).
- Cookie attributes:
HttpOnly(script cannot read it),Secure,SameSite=LaxorStrict,Path=/, noDomainand the__Host-prefix (browsers then refuse a cookie set by a sibling subdomain), per RFC 6265bis. - Lifetime: a new ID at login and on privilege change (stops fixation); an idle timeout and an absolute timeout; deletion on logout.
- CSRF: a cookie is sent automatically, so unsafe methods need a CSRF token
or an
Origincheck (OWASP CSRF cheat sheet).SameSitehelps but is not a replacement. - Use when: the caller is a browser and the app has a backend.
- Pitfalls: signed-cookie sessions cannot be revoked; a shared parent domain widens the cookie's reach; a store outage logs everyone out.
- Status: Adapter. See Sessions and cookies.
Access tokens: self-contained JWT or opaque
| JWT access token | Opaque token | |
|---|---|---|
| Standard | RFC 9068 profile of RFC 7519 | Any random string, validated by RFC 7662 introspection |
| Validation | Local: signature, iss, aud, exp |
Call the authorization server for each token, or cache the answer |
| Revocation | Waits for expiry unless every API checks a deny list | Immediate at the authorization server |
| Content visible to holder | Yes, unless encrypted | No |
| Cost | Key rotation and JWKS caching; short lifetimes | A network call and a dependency on the authorization server |
| Pitfalls | Algorithm confusion, missing aud check (RFC 8725); stale claims |
Introspection latency and availability |
| Status | Adapter (OidcAuthenticator) |
Out of scope until a broker issues opaque tokens |
Bearer tokens (RFC 6750) work for whoever holds them, so keep lifetimes short and never put them in URLs.
Refresh tokens and rotation
- What: A long-lived credential that gets new short-lived access tokens without another login (RFC 6749 §6).
- Best practice (RFC 9700): public clients get sender-constrained or rotating refresh tokens, and reuse of a rotated token revokes the whole family.
- Pitfalls: a refresh token held in a browser is the most valuable thing script can steal; rotation races between tabs.
- Status: Out of scope. A BFF keeps upstream tokens on the server and discards them by default (OIDC login). Native apps and machine clients manage refresh tokens with the broker.
Sender-constrained tokens
- What: A token bound to a key the client holds, so a stolen token is useless without the key. DPoP (RFC 9449) signs each request with a client key. Mutual TLS binding (RFC 8705) ties the token to a client certificate.
- Use when: tokens must live in an environment that can leak them (a browser client, a mobile app) or the data is high value.
- Pitfalls: support is needed at the authorization server and in every API; key storage in a browser is itself exposed to script.
- Status: Out of scope for the first version.
Browser options
OAuth 2.0 for Browser-Based Applications names three architectures and ranks them by security.
| Architecture | Who holds tokens | Cross-site-scripting exposure | Needs a backend of its own |
|---|---|---|---|
| Backend for frontend (BFF) | The backend; the browser has a session cookie | Script can make calls as the user while the page is open, but cannot take a token away | Yes |
| Token-mediating backend | The backend runs the flow, then hands the SPA an access token | Script can read the token from memory | Yes |
| Browser-based OAuth client | The SPA holds access and refresh tokens | Script can read tokens, or run its own silent authorization request | No |
The IETF ranks the BFF first for apps that have a backend, since moving tokens out of reach of script removes the largest class of theft. A browser-based client remains right when there is no backend of the app's own. Why the browser holds a session and the browser-client alternative apply this.
Status: BFF is the design's choice; the other two are Considered and rejected.
Token exchange for downstream calls
- What: A service swaps the token it received for a new token for another audience (RFC 8693). The result can keep the original user (delegation) or act as the service (impersonation, discouraged).
- Alternatives: call downstream with the service's own client-credentials token (no user identity), or forward the user's token (breaks audience restriction, so avoid).
- Status: Via broker; the application uses its own client-credentials token until it needs user delegation (Machine clients).
Revocation and logout
| Mechanism | What it does | Caveat | Status |
|---|---|---|---|
| Delete the server session | Ends local access at once | Does not end the IdP session | Adapter |
| OIDC RP-initiated logout | The app redirects to the provider's end-session endpoint | The user may be signed out of other apps too | Adapter, optional per provider |
| OIDC back-channel logout | The provider posts a signed logout_token carrying sub or sid |
Needs the session store to be searchable by sid |
Adapter |
| SAML Single Logout | Logout request and response between SP and IdP | Unreliable across IdPs; local timeouts do the real work | Via broker |
| Token revocation (RFC 7009) | The client asks the authorization server to revoke a token | JWTs still verify locally until expiry | Via broker |
Session and token comparison
| Pattern | Caller | Revocable at once | Server state | CSRF risk | Status |
|---|---|---|---|---|---|
| Server session cookie | Browser | Yes | Session store | Yes | Adapter |
| JWT access token | Service, native app | No, until expiry | None | No | Adapter |
| Opaque token + introspection | Service, native app | Yes | Authorization server | No | Out of scope until a broker issues them |
| Refresh token | Native app, service | At the authorization server | Authorization server | No | Out of scope |
| Sender-constrained token | High-value API | As above | Key at the client | No | Out of scope |
Authorization patterns
Where decisions happen
- Route level (coarse): may this caller reach this endpoint at all? A declarative check on permission, role or scope. Cheap, and it rejects early with 403.
- Resource level (fine): may this caller act on this record, and which records may they list? This needs the record, so it runs after loading it, or as a query filter.
- Query scoping: a list endpoint adds the caller's scope to the query. Filtering rows after fetching leaks existence through counts and breaks pagination (OWASP Authorization cheat sheet). Broken object-level authorization is the first item of the OWASP API Security Top 10.
- Deny by default, and return 404 instead of 403 when the existence of a record is itself sensitive.
- Status:
Requirementfor routes;ResourcePolicy.allowsandResourcePolicy.scopefor records (Authenticated request).
Models
| Model | Decides by | Strength | Weakness | Status |
|---|---|---|---|---|
| ACL | A list on each resource of who may do what | Direct and easy to explain | Does not scale across many resources; hard to audit globally | Custom in ResourcePolicy |
| RBAC (NIST RBAC, ANSI INCITS 359) | The caller's roles, mapped to permissions | Simple, auditable | Role explosion; no per-record rules | Adapter (permissions and roles) |
| ABAC (NIST SP 800-162) | Attributes of caller, resource, action and environment | Expresses tenant, ownership, time | Rules scatter through code unless centralized | Adapter through ResourcePolicy and context attributes |
| ReBAC | Relationships in a graph: "editor of a folder that contains this document" | Natural for sharing and hierarchies; Google's Zanzibar model, OpenFGA | Needs a relationship store kept in sync | Out of scope |
| OAuth scopes | What the resource owner delegated to a client | A ceiling on a token | Not a user's permission | Limit on bearer principals |
Scopes are a ceiling: a delegated call is allowed only when the user's permissions and the token's scopes both permit it.
Where the data comes from
- IdP claims and groups are a snapshot taken at login. They are good for coarse facts such as employment and group membership, and they go stale between logins.
- App-owned entitlements (roles, tenancy, org structure, ownership) live in the application's database and change independently of the IdP.
- Where the decision data sits: putting permissions in a token freezes them until expiry and grows every request. The design computes the authorization context per request from current data, behind a versioned cache (Authorization model, Authorization changes).
Policy engines and the PDP/PEP split
- Split (NIST SP 800-162, XACML): a policy enforcement point (PEP) intercepts the request and asks a policy decision point (PDP) for allow or deny. The PDP evaluates policy over attributes from a policy information point.
- Engines: OPA (Rego, general purpose), Cedar (AWS, analyzable policy language), OpenFGA (ReBAC). They move the rules out of application code and give one audit surface, at the cost of an extra component and a data-sync problem.
- In the design:
RequirementandResourcePolicyare the PEP seam. An engine would sit behindResourcePolicyas a PDP. No engine integration is in the design (Goals and non-goals).
UI mirroring
The UI needs to know what to show. It reads the user's effective permissions
from the server and hides features, but never decides: the server rechecks every
request. A stale UI fails safely with 403, and the client refetches. Status:
/auth/session (HTTP surface).
Authorization comparison
| Pattern | Best for | Ceiling | Status |
|---|---|---|---|
| Route-level requirement | Endpoint access | Cannot see the record | Adapter |
| Resource policy + query scope | Record-level rules, tenancy, ownership | Rules live in app code | Adapter |
| RBAC | Line-of-business apps | Role explosion | Adapter |
| ABAC | Tenant and ownership rules | Needs discipline to centralize | Adapter |
| ReBAC | Sharing, nested resources | Relationship store | Out of scope |
| External engine | Many services, shared audit | Extra component | Out of scope |
Mix and match
| Landscape | Authentication | Session and token | Authorization |
|---|---|---|---|
| Internal tool behind corporate SSO | OIDC direct to the corporate IdP, or SAML through a broker | Server session cookie | RBAC from IdP groups mapped to roles, plus a few resource rules |
| B2C app with social login | OIDC and OAuth 2.0 social, optional passkeys through a broker; no local passwords if avoidable | Server session cookie | RBAC for staff; ownership rules through ResourcePolicy for user data |
| B2B multi-tenant SaaS, per-customer SAML or OIDC | Broker that holds each customer's connection; link on (issuer, subject) | Server session for the web UI; bearer tokens for the customers' API clients | Tenant as an attribute, enforced in ResourcePolicy.scope; RBAC within a tenant |
| API-only service for machine clients | Client credentials or private_key_jwt at a broker |
JWT access tokens (RFC 9068), short-lived; opaque with introspection when immediate revocation matters | Scopes as the ceiling; service-account roles |
| SPA, mobile app and several APIs | Broker for all; code + PKCE in the system browser for native (RFC 8252) | BFF cookie for the SPA; bearer tokens for mobile and between APIs; token exchange for downstream | Shared permission catalog; each API enforces its own |
| Regulated or high-assurance app | Broker with phishing-resistant MFA (passkeys, hwk); acr and max_age for sensitive actions |
Server session with short idle timeout; sender-constrained tokens for APIs | ABAC with central policy; consider an external engine for audit; full audit log of decisions |
Independence rules
- AuthN knows nothing about carriage or AuthZ. An adapter ends in
ExternalIdentity. It does not decide session length, cookie format or permissions. - Carriage knows nothing about protocols. It stores an account or client ID and authentication metadata. It does not hold permissions or protocol artifacts such as assertions.
- AuthZ knows nothing about how the caller authenticated. It reads
Principal, never an IdP response, a cookie or a token. - Legitimate couplings, carried as data:
- Step-up needs
auth_timeandamrto flow from authentication through the session onto thePrincipal, so authorization can require a fresh or multi-factor login. - Logout needs
session_ref(sidorSessionIndex) to flow from authentication into the session store. - Delegated tokens need scopes on the
Principalso authorization can apply the ceiling. - Account resolution at login writes IdP attributes that the authorization context later reads.
- Step-up needs
Swapping any one layer should change only that layer's adapter and configuration.
Where this design sits
Each pattern's position in this design is in the design: the
adapters, the broker profile, account linking, the browser and machine carriage,
logout and the authorization model. The shipped behaviour is documented in the
rn-forge-auth guides.