Module openid_connect 

OpenID Connect authentication plugin (openid-connect).

Two modes, selected by bearer_only:

• Resource-server / bearer mode (bearer_only: true, the default): validates an OAuth2 / OIDC access token presented as a Bearer token in the Authorization header and, on success, exposes the token claims to downstream nodes via context.message. Validation is either local JWT verification against the provider’s JWKS (by kid, cached with a TTL, refetched once on an unknown kid) or RFC 7662 token introspection.

• Interactive login (bearer_only: false): the full Authorization Code flow with PKCE. An unauthenticated browser is redirected to the identity provider; the provider redirects back to redirect_uri with a code; the plugin exchanges it for tokens, validates the id_token, and seals the resulting claims into an encrypted client-side session cookie (see crate::plugins::util::cookie_session). Subsequent requests carrying a valid session cookie are let through with the claims attached. No server-side session store is needed, so this works across a horizontally-scaled deployment as long as every instance shares session.secret.

Flow wiring (interactive mode)

In interactive mode the node exits through its error port whenever it needs the browser to move (the 302 to the IdP, the post-callback 302 back to the original URL, or a 401); the prepared response already sits on the context. Wire the node’s error edge to client.in. Only a request that arrives with a valid session cookie continues out the success port toward the upstream. The node must be on a route whose match rule also covers the redirect_uri path so the callback reaches it.

Deviations from APISIX

• No server-side session revocation. Sessions live entirely in the encrypted cookie, so a session cannot be invalidated before its session.cookie.lifetime expiry without a shared denylist (a future feature). Use short lifetimes. This is the standard client-side-cookie trade-off APISIX shares when configured for cookie sessions.
• No token refresh in this version: when the session cookie expires the user re-authenticates (a fresh, fast redirect round-trip if the IdP session is still valid).
• Only the Authorization Code grant is implemented (the OIDC gateway case); implicit/hybrid flows are not.

Structs

CachedJwks 🔒

Cached JWKS with the time it was fetched, for TTL-based expiry.

FlowState 🔒

Transient state carried in the short-lived flow cookie across the redirect to the IdP and back to the callback (CSRF state, replay nonce, PKCE verifier, and where to send the browser after login).

Interactive 🔒

Interactive-mode configuration, present only when bearer_only: false.

Jwk 🔒

A single JSON Web Key from a provider’s JWKS document.

JwkSet 🔒

A JWKS document ({ "keys": [ ... ] }).

OpenidConnectPlugin

Authenticates requests by validating a bearer access token via JWKS signature verification or token introspection.

SessionData 🔒

The sealed session payload: the validated identity, kept small.

Functions

alg_matches_kty 🔒

Whether alg can be verified with a key of JWK type kty.

algs_for_key 🔒

Narrows the configured algorithms to those a kty key can verify.

audience_contains 🔒

True when aud equals client_id (string aud) or contains it (array aud).

build_interactive 🔒

Builds the interactive-mode configuration from the plugin config.

decode_and_validate 🔒

Verifies the token signature (against key, restricted to allowed_algs) and exp, returning the decoded claims. Issuer/audience are validated separately by OpenidConnectPlugin::validate_claims.

first_query 🔒

First value of a query parameter.

form_encode 🔒

Percent-encodes a token for an application/x-www-form-urlencoded body.

jwk_to_decoding_key 🔒

Builds a [DecodingKey] from a JWK based on its key type.

parse_alg 🔒

Parses one algorithm name into a [jsonwebtoken::Algorithm] (asymmetric only — OIDC JWKS keys are RSA/EC).

parse_allowed_algs 🔒

Parses token_signing_alg_values_expected (string, comma/space list, or array) into the allowed-algorithm set, defaulting to the common asymmetric algorithms.

parse_bearer 🔒

Extracts the bearer token from an Authorization header value.

parse_introspection 🔒

Parses an RFC 7662 introspection response, requiring active: true.

pkce_challenge 🔒

PKCE S256 challenge: base64url(SHA-256(verifier)).

random_token 🔒

A URL-safe random token (32 bytes → base64url) for state/nonce/PKCE.

read_audience_cfg 🔒

Reads claim_validator.audience.{claim,required,match_with_client_id}.

read_valid_issuers 🔒

Reads claim_validator.issuer.valid_issuers.

redirect 🔒

Prepares a 302 redirect on the context and exits through the error port (the node’s error edge should be wired to client.in).

request_is_https 🔒

True when the request arrived over HTTPS (controls the cookie Secure flag).

request_uri 🔒

Rebuilds the request URI (path plus sorted query string) for the post-login redirect target.

select_jwk 🔒

Selects the JWK matching kid, or the sole key when no kid is present.

session_cookie_field 🔒

Reads a session cookie string field from nested session.cookie.<field>, falling back to the flat session_cookie_<field> form the Web UI schema emits (the SchemaForm is flat and cannot author nested maps).

session_field 🔒

Reads session.<field> as a string.

string_opt 🔒

Reads an optional non-empty string config value.

url_path 🔒

Extracts the path portion of a URL (everything from the first / after the authority), defaulting to /.