Skip to main content
Identity Authority
Category: OAuth & OIDC

JSON Web Key Set

Also known as: JWKS, JWK Set, JWKS URI
Simply put

A JSON Web Key Set (JWKS) is a document, formatted in JSON, that publishes a collection of public keys. Systems use these keys to check that a security token, such as a JSON Web Token (JWT), was genuinely issued by the expected authority and has not been tampered with. Because the keys are public, the JWKS can be shared openly so that many clients and services can perform verification independently.

Formal definition

A JSON Web Key Set is a JSON data structure, defined alongside the JSON Web Key (JWK) format in RFC 7517, containing a 'keys' array of one or more JWK objects. In typical IAM deployments it publishes the public keys corresponding to the signing keys an authorization or identity provider uses, so relying parties can validate the signature of a JWT (for example an OIDC ID token or an OAuth 2.0 JWT access token) without holding a shared secret. The set is commonly exposed at a JWKS URI, frequently discoverable via OIDC provider metadata, and its inclusion of a key identifier ('kid') on each key lets verifiers select the correct key and supports key rotation. Note that publishing keys in a JWKS enables signature verification, which establishes that a token was signed by the holder of the corresponding private key; it does not by itself encrypt tokens, and a signed token is not a confidential one. The precise contents (algorithm families, key types, and whether private key material is ever represented) depend on the JWK spec and the deployment's configuration; JWKS endpoints intended for verification publish only public keys.

Why it matters

JWKS is the mechanism that lets distributed systems verify token signatures without sharing a secret. In a federated or microservices architecture, an authorization or identity provider signs tokens with a private key, and any number of relying parties can independently validate those signatures by fetching the corresponding public keys from a JWKS endpoint. This decouples the issuer from its verifiers: services do not need pre-shared symmetric keys, and new consumers can begin validating tokens simply by retrieving the published key set. For OIDC and OAuth 2.0 deployments that issue signed JWTs (such as OIDC ID tokens or JWT access tokens), the JWKS is a foundational trust anchor.

JWKS also makes key rotation operationally manageable. Because each key carries a key identifier ('kid'), an issuer can publish new signing keys alongside existing ones, allowing verifiers to select the correct key per token during transition periods. This supports rotating signing keys without a hard cutover that would break in-flight tokens. Misconfiguration or careless handling of JWKS, however, has security consequences: verifiers that fetch keys over untrusted channels, fail to pin or validate the expected issuer, or accept unexpected algorithms can be exposed to token forgery risks.

It is important to be precise about what JWKS does and does not provide. Publishing public keys enables signature verification, which establishes that a token was signed by the holder of the corresponding private key and has not been tampered with. It does not encrypt tokens or make their contents confidential, a signed token is not a private one. Treating signature verification as if it also guaranteed confidentiality is a common conceptual error that JWKS-based designs must avoid.

Who it's relevant to

IAM and Security Architects
Architects designing federated or microservices-based systems rely on JWKS as the trust anchor for token signature verification. They must decide how verifiers discover and cache the JWKS, how issuers are pinned, and how key rotation is coordinated across relying parties without breaking in-flight tokens.
API and Backend Engineers
Engineers implementing resource servers or API gateways that validate OIDC ID tokens or OAuth 2.0 JWT access tokens use the JWKS to fetch public keys and verify signatures. They need to handle 'kid'-based key selection, tolerate key rotation, and restrict accepted algorithms to avoid verification bypass.
Identity Provider and Authorization Server Operators
Teams operating identity or authorization servers publish and maintain the JWKS endpoint, manage the lifecycle of signing keys, and orchestrate rotation by serving new keys alongside existing ones. They are responsible for ensuring only public key material is exposed and that the endpoint remains available to verifiers.
Security Auditors and Compliance Reviewers
Reviewers assessing token-based access flows examine how JWKS is fetched, cached, and validated, whether key rotation is handled safely, and whether verifiers correctly distinguish signature verification from confidentiality. This helps confirm that token trust is established as intended rather than assumed.

Inside JWKS

keys array
The top-level 'keys' member of a JWKS is a JSON array containing one or more JSON Web Keys (JWKs). Multiple keys are typically present to support key rotation and to allow relying parties to select the correct verification key.
kty (key type)
Identifies the cryptographic algorithm family of each key, such as RSA or EC. This parameter is required in a JWK and determines which other members are expected to be present.
kid (key identifier)
A hint used to match a token to the specific key that should verify it. A JWT header commonly carries a 'kid' that a consumer uses to locate the corresponding key in the JWKS, which is useful during rotation when multiple keys coexist.
use and key_ops
Optional parameters indicating the intended purpose of a key. 'use' distinguishes signature ('sig') from encryption ('enc'), while 'key_ops' enumerates permitted operations. In most token-validation deployments the relevant keys are signature keys.
alg (algorithm)
An optional parameter identifying the algorithm intended for use with the key, for example RS256 or ES256. When present it helps a consumer confirm the key is appropriate for the token's declared algorithm.
public key material
Algorithm-specific members carrying the public key values, such as 'n' and 'e' for RSA or 'x', 'y', and 'crv' for EC keys. A JWKS published for token verification typically exposes only public key material, not private keys.

Common questions

Answers to the questions practitioners most commonly ask about JWKS.

Does publishing a JWKS mean my tokens are encrypted?
No. A JWKS typically publishes public keys used to verify signatures on tokens such as JWTs, not to encrypt them. Signature verification confirms integrity and origin of a token, but a signed token remains readable to anyone who can decode it unless it is separately encrypted (for example as a JWE). Do not treat JWKS availability as evidence that token payloads are confidential; if you need confidentiality, that is a distinct concern from signing key distribution.
Is a JWKS an authentication mechanism on its own?
No. A JWKS is a distribution format for cryptographic keys, most commonly the public keys a relying party uses to validate token signatures. It is a supporting component within flows such as OpenID Connect (which layers authentication on OAuth 2.0), not an authentication protocol itself. Identification, authentication, and authorization are separate steps; a JWKS only helps a verifier trust that a token was signed by the expected issuer, which is one input to those steps rather than the whole process.
How does a relying party locate the correct key in a JWKS to verify a given token?
In most deployments the JWT header includes a key identifier (the kid claim), and the verifier matches that value against the kid of an entry in the JWKS to select the corresponding public key. When a kid is absent, implementations may fall back to trying candidate keys by algorithm or key type, though behavior varies by library and configuration. As a defensive measure, verifiers typically also confirm that the key's algorithm and intended use align with the token's alg header rather than trusting the header alone.
How should clients handle caching and refreshing of a JWKS endpoint?
Because JWKS endpoints are fetched over the network, most verifiers cache the retrieved keys to avoid a request on every validation. Caching duration is often guided by HTTP cache headers where present, or by a configured interval. A common pattern is to refresh when an unknown kid is encountered, which supports key rotation without a fixed schedule, while applying rate limiting to avoid hammering the endpoint on repeated unknown-kid failures. Exact caching semantics depend on the client library and deployment configuration.
How does JWKS support signing key rotation?
A JWKS can contain multiple keys simultaneously, which lets an issuer publish a new signing key alongside the outgoing one before switching over. Depending on the rotation strategy, tokens signed with either key can be validated during the overlap window because both keys remain in the set, and the kid ties each token to its key. Retiring a key generally involves removing it from the JWKS only after tokens signed with it are no longer expected to be in use. The specific rotation cadence and overlap period are deployment decisions.
What should a verifier check before trusting keys retrieved from a JWKS endpoint?
In most secure deployments the verifier fetches the JWKS over TLS from an issuer-associated endpoint (often discovered via provider metadata) so it can trust the transport and origin of the keys. Beyond transport, verifiers typically validate that a selected key's type and permitted algorithm are appropriate for the token being checked and reject unexpected or downgraded algorithms. What lies outside the scope of the JWKS itself, such as validating token claims like issuer, audience, and expiry, remains a separate part of token validation that the JWKS does not perform.

Common misconceptions

A JWKS proves that a token is authentic and trustworthy by itself.
A JWKS supplies the public keys used to verify a signature; verifying the signature confirms integrity and origin, but the consumer must still validate claims such as issuer, audience, and expiration. Possessing the keys is one step in validation, not the whole process.
Because keys are published in a JWKS, the tokens they verify are encrypted or confidential.
A JWKS for signature keys enables verifying that a signed token was not tampered with. Signing is not encryption, and the presence of a public signing key says nothing about whether token contents are encrypted.
A JWKS should contain a single key that never changes.
A JWKS commonly contains multiple keys precisely to support rotation. Consumers should be prepared to handle several keys and to refresh the set, typically selecting the correct one via the token's 'kid'.

Best practices

Select the verification key by matching the token header's 'kid' against the entries in the JWKS rather than assuming a single key is present.
Cache the fetched JWKS but refresh it when an unrecognized 'kid' is encountered, so that key rotation does not break validation.
Publish only public key material in a JWKS intended for token verification, and never expose private keys through the endpoint.
Confirm that the key's algorithm and intended use ('alg', 'use', 'key_ops' where present) are consistent with the token's declared algorithm before verifying.
Treat successful signature verification as only one step, and continue to validate issuer, audience, expiration, and other claims before granting access.
Retrieve the JWKS over a protected transport and from the expected issuer location, so the trust in the published keys is well founded.
Promotional banner for the Pentest Readiness checklist download