Skip to main content

Module oidc

Module oidc 

Source
Expand description

OIDC token validation — “the forthcoming verifier” (UT-1, UT-S01 D1).

This module is the verifier that verified_user.rs was built to wait for. It implements the UT-S01 resolution model: every plexus backend validates tokens locally, with zero shared secrets —

  1. Backend config names its trusted issuer URL and audience (OidcConfig).
  2. The validator fetches {issuer}/.well-known/openid-configuration (OIDC Discovery) and reads jwks_uri.
  3. It fetches the JWKS (RFC 7517), selects the key by the JWT header kid, and caches per the AUTH-8 policy (see “Caching policy”).
  4. It validates the RS256 signature plus the standard claims: iss (== configured issuer), aud (== configured audience), exp/nbf/iat (zero leeway — no grace), sub present.
  5. On success it mints the sealed VerifiedUser — the only production call site of VerifiedUser::new_sealed — carrying the TenantId from the org_id claim (UT-S01 D3).

§The Auth0-interchangeability bar (UT-S01 D2)

The validator’s only coupling to the IdP is (issuer URL, audience, the five standard claims, org_id). Pointing OidcConfig at a real Auth0 tenant (https://<tenant>.auth0.com/) with the backend registered as an Auth0 API is a zero-code-change swap. The plexus extensions roles / username are read if present and optional for validation, per the bar’s negative-space rule.

§Caching policy (AUTH-8, adopted verbatim)

ConditionBehavior
JWKS fetch succeedscache keys; TTL = min(Cache-Control: max-age, 3600 s); default 3600 s
JWKS max-age below 60 sTTL floored at 60 s (IDENTITY-27) — max-age=0 cannot make every validation a fetch
Token kid not in cacheone refresh, then reject (UnknownKeyId) — at most one such refresh per 60 s per validator, and concurrent refreshes coalesce into one (IDENTITY-27)
IdP unreachable, cache presentkeep validating with cached keys (degraded) — usable only for tokens whose exp is in the future, because exp is enforced with zero grace regardless
IdP unreachable, no cachereject (JwksUnavailable / Discovery)
Discovery names a jwks_uritrusted only if https, or on the issuer’s own origin (IDENTITY-27)
Fetched documentsat most 1 MiB, no redirects followed (ReqwestJwksFetcher, IDENTITY-27)
Degradation transitionsauth_provider_degraded / auth_provider_restored events under target = "plexus::auth"

§Algorithm posture

RS256-only for now (maximum Auth0 / off-the-shelf-middleware compatibility — UT-S01 open question 4). The design is EdDSA-extensible: key admission lives in one match in jwks::admit_key, and the per-token algorithm gate lives in one check in validator.rs — adding EdDSA is one arm in each.

§No-network testing

JwksFetcher is the injection seam: tests supply a fixture fetcher serving a canned discovery document and JWKS (see tests/oidc_validator.rs). The production fetcher (ReqwestJwksFetcher) is feature-gated behind oidc-reqwest.

Re-exports§

pub use config::Audience;
pub use config::AudienceClaim;
pub use config::AudienceError;
pub use config::OidcConfig;
pub use fetch::FetchError;
pub use fetch::FetchedDocument;
pub use fetch::JwksFetcher;
pub use session::OidcSessionValidator;
pub use validator::OidcError;
pub use validator::OidcValidator;
pub use validator::VerifiedToken;

Modules§

config
Validator configuration: trusted issuer + expected audience (UT-1).
fetch
JwksFetcher — the validator’s HTTP seam (UT-1).
session
OidcSessionValidator — the framework SessionValidator over the OIDC validator (UT-1, UT-S01 D4 step 3).
validator
OidcValidator — RS256 token validation against a discovered JWKS (UT-1, UT-S01 D1; caching per AUTH-8; test matrix per AUTH-2).