Skip to content

Token profiles

rn_forge.auth.oidc verifies JWTs for bearer authentication, the OIDC callback and back-channel logout. It needs the oidc extra and is imported directly. The core never imports it. The contracts it feeds are in Contracts; the in-process provider for testing it is in Testing.

OIDC bearer tokens

OidcAuthenticator is an Authenticator for Bearer credentials. It verifies the token with a JwtVerifier, then maps the claims with claims_to_principal, which defaults to principal_from_claims. A scheme other than Bearer raises AuthenticationFailed.

Build it once at startup with discovery, which reads the issuer's /.well-known/openid-configuration:

from rn_forge.auth.oidc import OidcAuthenticator

authenticator = OidcAuthenticator.from_issuer(
    "https://login.example.com/",
    audience="orders-api",
)

Or pin the key-set URL and skip discovery, for an identity provider that publishes no discovery document:

authenticator = OidcAuthenticator.from_jwks_url(
    "https://login.example.com/keys",
    issuer="https://login.example.com/",
    audience="orders-api",
)

Discovery runs once, inside from_issuer; the authenticator then holds the key set cache, so reuse one instance rather than building one per request. The discovery document's issuer must equal the issuer it was fetched for, and a mismatch raises TokenVerificationError.

Verification requires exp, iss and aud as well as checking them. A token without exp is rejected rather than treated as non-expiring. The algorithms list, ("RS256",) by default, is an allow-list: a token whose header names another algorithm, including none, is rejected. The header must carry a kid. leeway tolerates clock skew, in seconds, on exp, nbf and iat.

Token profiles

An identity provider issues several kinds of JWT, and each has its own verifier used at exactly one place. A token valid under one is never accepted by another.

Verifier Used at Accepts
JwtVerifier Bearer authentication on API routes An access token.
IdTokenVerifier The OIDC callback An ID token for your login client, checked against the nonce you sent.
LogoutTokenVerifier The back-channel logout endpoint A logout token, accepted once.

JwtVerifier takes mode. With "rfc7519" (the default) it accepts a typ of JWT or none, requires iss, aud and exp, and validates sub, nbf and iat when present. With "rfc9068" it accepts only typ at+jwt or application/at+jwt and requires iss, exp, aud, sub, client_id, iat and jti. In both modes it rejects any token that carries nonce or events, which an ID token and a logout token do.

Pass your OIDC login client ID as login_client_id. An API audience equal to it is refused with ValueError unless mode="rfc9068", because otherwise an ID token issued to your login client would pass as an access token.

IdTokenVerifier.verify(token, nonce=..., access_token=...) checks signature, iss, aud, azp, exp, iat, nonce and, when an access token is given, at_hash. With max_age set, auth_time is required and must be no older than that many seconds.

LogoutTokenVerifier needs a ReplayStore, such as InMemoryReplayStore (one process only). It requires the back-channel logout event, a sid or sub, no nonce, an iat no older than max_age_seconds (120 by default), and a jti it has not accepted before. The jti is stored under "{iss}|{jti}" until the token expires, and only once every other check has passed.

All three build with from_issuer or from_jwks_url, and all refuse a key-set URL that is not HTTPS.

The key-set cache

Signing keys come from PyJWT's PyJWKClient, configured by two options on from_issuer and from_jwks_url:

Option Default Meaning
lifespan 300 seconds How long a fetched key set stays cached.
cooldown_duration 30 seconds The fewest seconds between two key set fetches. A token with an unknown kid triggers a refetch only after this long.

The cooldown bounds how often a stream of tokens with unknown kid values can make the process call the identity provider.

The HTTPS rule

The adapter fetches key material only over HTTPS. Plain HTTP is accepted only for localhost, 127.0.0.1 and ::1, which is what a test server needs. fetch_json, which reads the discovery document, checks its URL, and the JWKS URL, whether it came from discovery or from from_jwks_url, is checked too; a violation raises TokenVerificationError. The fetch argument of from_issuer replaces fetch_json for the discovery document only, so a replacement transport owns the check on that one URL. The key set itself is always fetched by PyJWKClient.

Failure reasons are for logs

TokenVerificationError carries the specific reason a token, key set or discovery document failed: an expired token, an unknown kid, an audience mismatch. The reason is for logs. OidcAuthenticator re-raises it as AuthenticationFailed so the framework binding can log it, and the response body must never repeat it: a 401 body is AUTH_FAILED_DETAIL, so a caller cannot tell which check failed.