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 —
- Backend config names its trusted issuer URL and audience
(
OidcConfig). - The validator fetches
{issuer}/.well-known/openid-configuration(OIDC Discovery) and readsjwks_uri. - It fetches the JWKS (RFC 7517), selects the key by the JWT header
kid, and caches per the AUTH-8 policy (see “Caching policy”). - It validates the RS256 signature plus the standard claims:
iss(== configured issuer),aud(== configured audience),exp/nbf/iat(zero leeway — no grace),subpresent. - On success it mints the sealed
VerifiedUser— the only production call site ofVerifiedUser::new_sealed— carrying theTenantIdfrom theorg_idclaim (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)
| Condition | Behavior |
|---|---|
| JWKS fetch succeeds | cache keys; TTL = min(Cache-Control: max-age, 3600 s); default 3600 s |
JWKS max-age below 60 s | TTL floored at 60 s (IDENTITY-27) — max-age=0 cannot make every validation a fetch |
Token kid not in cache | one 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 present | keep 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 cache | reject (JwksUnavailable / Discovery) |
Discovery names a jwks_uri | trusted only if https, or on the issuer’s own origin (IDENTITY-27) |
| Fetched documents | at most 1 MiB, no redirects followed (ReqwestJwksFetcher, IDENTITY-27) |
| Degradation transitions | auth_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 frameworkSessionValidatorover 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).