Module oidc 

OpenID Connect: discovery, token introspection, revocation, token exchange, and the authorization-code + PKCE relying-party flow (DW-034).

The gateway acts as an OIDC client (relying party) for two distinct purposes:

1. Token introspection (RFC 7662) — on the request path, a presented Authorization: Bearer token that did not verify against any JWT provider (DW-019) is introspected against the configured OIDC provider’s introspection endpoint. An active: true result resolves an Identity; active: false (or a non-2xx) is a 401. Introspection results are cached keyed by the token’s SHA-256 hash with a configurable TTL — a cached active: true short-circuits the IdP call, while a cached active: false is NOT cached (re-checked on the next request so a revoked token is noticed promptly).
2. Authorization-code + PKCE (RFC 6749 section 4.1 + RFC 7636) — the user-facing login flow: the gateway redirects an unauthenticated request to the IdP’s authorization endpoint with a PKCE code challenge, handles the callback, and exchanges the code for access/refresh/ID tokens. This is the relying-party role; the resulting tokens are stored in a session cookie.

Two management operations round out the flow:

• Token revocation (RFC 7009) — POST to the revocation endpoint to revoke a token. An admin/CLI operation, not on the hot request path.
• Token exchange (RFC 8693) — exchange a subject token (the client’s bearer token) for an actor token for an upstream, using the urn:ietf:params:oauth:grant-type:token-exchange grant type. This extends the OAuth2 client-credentials proxying pattern (DW-035).

Discovery

The provider’s discovery document is fetched from {issuer}/.well-known/openid-configuration (RFC 8414 / OIDC Discovery 1.0) and cached for the provider’s lifetime (it rarely changes). The document supplies the introspection, revocation, authorization, and token endpoints; config-level overrides (introspection_endpoint, revocation_endpoint) take precedence over the discovered values.

HTTP

All IdP HTTP calls use the OidcConnector (plain-or-TLS, the JwksConnector/OAuth2Connector pattern), reusing the workspace rustls stack with no new HTTP dependencies. A trusted_ca_file replaces the webpki public roots for an IdP behind a private CA (the same trust model as JwtProvider::trusted_ca_file).

Error posture

An introspection failure (network error, non-2xx, malformed response) is governed by the provider’s fail_open config: default false (fail closed = 401, the gateway refuses to authenticate a token it cannot introspect); true treats the failure as anonymous (pass-through). Fail-open trades security for availability. The error envelope never leaks the IdP’s response body or headers.

Caching

The introspection cache (OidcIntrospectionCache) lives on the dataplane (carried across generation swaps, the jwks_caches / oauth2_token_cache precedent) so a config reload never discards a cached active: true result. Entries are keyed by {provider_name}:{sha256_hex(token)} and expire after introspection_cache_ttl_s. The discovery document is cached per-provider on the OidcClient (rebuilt per generation, like OAuth2Client).

Structs

DiscoveryDocument

The parsed OIDC discovery document (RFC 8414 / OIDC Discovery 1.0). Only the fields the gateway consumes are extracted; unknown fields are ignored (the document is forward-compatible by design).

IntrospectionResponse

The parsed token introspection response (RFC 7662 section 2.2). active is the only REQUIRED field; the rest are optional and extracted as strings for the identity map.

OidcClient

One configured OIDC provider at runtime: config + HTTP client + cached discovery document. The introspection cache lives on the dataplane (OidcIntrospectionCache) so a config reload reuses cached results.

OidcIntrospectionCache

Per-provider introspection cache (DW-034): lives on the dataplane so a config reload reuses cached active: true results (the jwks_caches / oauth2_token_cache precedent). Entries are keyed by {provider_name}:{sha256_hex(token)}. Only active: true results are cached; active: false is re-checked on every request so a revoked token is noticed promptly.

TokenSet

The token set returned by an auth-code exchange (RFC 6749 section 5.1 + OIDC id_token). All fields except access_token are optional.

Enums

OidcError

Error contacting an OIDC provider (DW-034). The Display text is logged, not sent to the client (the envelope never leaks IdP internals). All variants surface to the client as 401 (fail closed) or pass-through (fail open) per the provider’s fail_open config.

Functions

pkce_code_challenge

Derive the PKCE code challenge (S256) from a verifier: the base64url(sha256(verifier)) per RFC 7636 section 4.2.

pkce_code_verifier

Generate a PKCE code verifier (43..=128 random ASCII characters per RFC 7636 section 4.1). Returns the verifier; the challenge is base64url(sha256(verifier)) (S256 method). The verifier MUST be sent in the token exchange; the challenge is sent in the authorization request. Uses a caller-provided 32-byte random seed (the gateway does not pull in a crypto RNG crate; tests pass a fixed seed for determinism, production callers use the OS RNG).