Cybersecurity glossary
What is a JSON Web Key Set (JWKS)?
Learn what a JSON Web Key Set (JWKS) is, how jwks_uri discovery works, how key rotation uses multiple JWKs, and which controls keep JWKS endpoints safe for JWT verification.
Definition
A JSON Web Key Set (JWKS) is a JSON document that contains an array of JSON Web Keys, typically published at a discovery URL so relying parties can retrieve the public keys needed to verify signatures or encrypt tokens for an issuer.
Why JWKS matters
Distributed verification only works if every relying party can find the issuer’s current public keys. A JSON Web Key Set (JWKS) is the usual answer: one document, many keys, fetched over HTTPS and matched by kid or algorithm policy.
JWKS is operational plumbing for JWT and OpenID Connect. When the endpoint is wrong, stale, or attacker-influenced, signature checks either break availability or—worse—accept forged tokens.
What a JWKS document contains
keys array
The required top-level field holding zero or more JWK objects used for crypto operations.
Per-key kid values
Identifiers that help map a token header to the correct JWK during rotation.
Algorithm metadata
Optional alg/use hints that describe intended signature or encryption usage.
Only public material
Production JWKS responses should never include private or symmetric secret fields.
Typical JWKS discovery and verification flow
Client learns the issuer
From configuration or token iss, the relying party identifies the authorization server.
Metadata reveals jwks_uri
OIDC/OAuth metadata points to the JWKS HTTPS endpoint for that issuer.
JWKS is fetched and cached
The verifier downloads the keys document and stores it with a controlled TTL.
Token presents a kid
The JWT/JWS header indicates which published key should verify the signature.
Matching JWK is selected
The verifier resolves kid against the local JWKS map under algorithm constraints.
Signature and claims are checked
After crypto verification, iss, aud, exp, and authorization claims are validated.
Rotation patterns that keep tokens verifiable
| Phase | JWKS content | Token signing |
|---|---|---|
| Steady state | Current signing key published | All new tokens use current kid |
| Introduce next key | Current + next keys both published | Still signing with current kid |
| Cut over | Current + previous (and optionally next) | New tokens use next kid |
| Retire | Remove previous after TTL window | Only active kids remain |
Hardening JWKS consumption
- Resolve JWKS only from configured issuer metadata—not from untrusted jku/x5u header URLs.
- Enforce HTTPS, certificate validation, and host allowlists for jwks_uri.
- Cache keys, but refresh on unknown kid with backoff and fetch rate limits.
- Reject JWKS entries that include private fields or weak cryptographic parameters.
- Bind expected algorithms to key types before verification.
- Monitor JWKS fetch failures and sudden key-set churn as security signals.
- Align key retirement with maximum access-token lifetime to avoid verification outages.
- Document ownership of the JWKS endpoint as part of identity infrastructure inventory.
The practical takeaway
A JWKS is the published set of JWKs that lets APIs and apps verify an issuer’s tokens at scale. It is both a convenience and a trust boundary.
Publish only public keys, rotate with overlap, constrain discovery to known issuer metadata, and treat key selection as policy—not free-form attacker input. Pair this with solid JWK and JWT claim validation for end-to-end token security.
Related security terms
JSON Web Key (JWK)
The individual key objects contained inside a JWKS document.
JWT (JSON Web Token)
Tokens commonly verified using public keys from a JWKS.
OpenID Connect (OIDC)
Identity layer that advertises jwks_uri for ID token verification.
JWT kid Injection
Attacks that abuse key selection when resolving kids against a JWKS.
JSON Web Signature (JWS)
Signed JOSE objects verified with keys discovered via JWKS.
Frequently asked questions
What is a JWKS in simple terms?
A JWKS is a published list of public keys in JSON. Apps that receive JWTs download that list to find the right key and check that the token was really signed by the issuer.
Where is a JWKS usually hosted?
Often at a TLS-protected URL advertised as jwks_uri in OpenID Provider metadata or OAuth authorization server metadata.
Why does a JWKS contain multiple keys?
Multiple keys support rotation: new tokens can use a new kid while older keys remain available until previously issued tokens expire.
Should a JWKS include private keys?
No. Public JWKS endpoints must expose only public key parameters. Private or symmetric material belongs in protected key stores.
How often should clients refresh a JWKS cache?
Cache with a bounded TTL and refresh on unknown kid or verification failure against cached keys, while rate-limiting fetches to avoid abuse loops.
Is fetching any JWKS URL from a token header safe?
No. Headers like jku must not freely redirect verifiers to attacker-controlled key sets. Constrain discovery to configured issuer metadata.
What happens if rotation removes a key too early?
In-flight tokens signed with the retired kid fail verification, causing outages. Keep overlapping publication windows aligned to token lifetime.
References
Explore authoritative guidance and frameworks related to json web key set (jwks).
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.