app.auth.oidc

RS256 bearer-token validation against the configured OIDC provider.

The backend is a stateless resource server (module-auth-oidc): it never takes part in the login flow. OidcValidator resolves the JWKS URI from the provider’s discovery document (<authority>/.well-known/openid-configuration) lazily, on the first token it validates – never at import or startup, so an unreachable IdP never stops the application. The resulting jwt.PyJWKClient is cached (it caches the key set and refetches on an unknown kid). A failed discovery is not cached; the next request retries.

Validation: signature (RS256 only), exp, nbf (when present), aud (ADRIANO_OIDC_AUDIENCE), iss (ADRIANO_OIDC_ISSUER, or the discovery document’s issuer when unset); exp, iss, aud and sub are required. No custom crypto: PyJWT does all of it.

Both the discovery request and the JWKS fetch use the shared outbound TLS context of app.tls (ADRIANO_TLS_VERIFY, ADRIANO_EXTRA_CA_CERTS).

Failures: an unacceptable token raises AuthenticationError (HTTP 401); an unreachable or broken discovery document or JWKS endpoint raises AuthUnavailableError (HTTP 503). Token values are never logged or echoed.

Public API: REQUIRED_CLAIMS, OidcValidator, cached_oidc_validator().

app.auth.oidc.REQUIRED_CLAIMS = ('exp', 'iss', 'aud', 'sub')

Claims every accepted token (real or dev) must carry.

class app.auth.oidc.OidcValidator(authority, issuer, audience, *, transport=None, jwks_client_factory=None, ssl_context=None)

Bases: object

Validates RS256 tokens issued by one OIDC provider.

Parameters:

  • authority (str) – Discovery base URL (ADRIANO_OIDC_AUTHORITY).

  • issuer (str | None) – Expected iss; None uses the discovery document’s issuer.

  • audience (str) – Expected aud.

  • transport (BaseTransport | None) – Optional httpx transport for the discovery request (tests inject a mock).

  • jwks_client_factory (Callable[[str], PyJWKClient] | None) – Builds the JWKS client from the URI (tests inject one serving local keys); None uses the production client.

  • ssl_context (SSLContext | None) – TLS context of the discovery and JWKS requests (see app.tls); None uses the default outbound context.

decode(token)

Validate an RS256 token and return its claims.

Parameters:

token (str) – Raw bearer token.

Return type:

dict[str, Any]

Returns:

The verified claims.

Raises:
app.auth.oidc.cached_oidc_validator(authority, issuer, audience, tls_verify=True, extra_ca_certs=())

Return the process-wide validator for one provider configuration.

Caching keeps the discovery result and the JWKS cache across requests. The TLS settings are part of the key as plain values; the context comes from app.tls.outbound_ssl_context().

Parameters:

  • authority (str) – Discovery base URL.

  • issuer (str | None) – Expected iss, or None.

  • audience (str) – Expected aud.

  • tls_verify (bool) – Whether to verify the provider’s certificate (ADRIANO_TLS_VERIFY).

  • extra_ca_certs (tuple[Path, ...]) – Extra trusted CA paths (ADRIANO_EXTRA_CA_CERTS).

Return type:

OidcValidator

Returns:

The shared validator.

Raises:

app.errors.ConfigurationError – If an extra CA path cannot be loaded.