Skip to main content

Module jwks

tokenkit

Module jwks 

Source
Available on crate feature jwks only.
Expand description

JWKS fetching and caching with automatic rotation on kid miss. JWKS fetching and caching with automatic rotation on kid miss.

Enabled with the jwks feature. JwksCache fetches a JSON Web Key Set from a URL, caches the decoded keys for a configurable TTL, and re-fetches whenever a token references an unknown kid — so rotated keys are picked up without restarts or redeploys.

§Hardening

  • Algorithm pinning: when a JWK advertises an alg member, tokens whose header claims a different algorithm are rejected with JwtError::AlgorithmMismatch — a key published for one algorithm never verifies tokens claiming another (alg-confusion defense). When the JWK carries no alg, the caller’s configured Validation algorithm is the only accepted one (enforced by jsonwebtoken).
  • Single-flight refresh: N concurrent misses trigger exactly one fetch; waiters reuse the result.
  • Minimum refresh interval: after a fetch, further on-miss refreshes are skipped for 10 seconds (configurable via JwksCache::with_min_refresh_interval), so a flood of unknown-kid tokens cannot hammer the JWKS endpoint.

§Example

use jsonwebtoken::{Algorithm, Validation};
use tokenkit::jwks::JwksCache;

let cache = JwksCache::new("https://issuer.example.com/.well-known/jwks.json");
let mut validation = Validation::new(Algorithm::RS256);
validation.set_required_spec_claims(&["exp", "iss"]);
let claims: serde_json::Value = cache.decode("header.payload.signature", &validation).await?;

Structs§

JwksCache
A cached JWKS key set fetched from a remote URL (or provided locally).