JWKS and kid explained: how verifiers find the right public key

Fetch the JWKS from a URL you configured, pick the key by kid, check that its type and alg fit the token, and cache the set. Never load keys from a URL inside the token.

A JSON Web Key (JWK) is a public key written as JSON, defined in RFC 7517. An RSA key has kty "RSA" with its modulus n and exponent e. An EC key has kty "EC", a curve and its x and y coordinates. A JWKS is an object with a keys array of them. Issuers publish a JWKS at a stable URL, and each token's header carries a kid that names the key that signed it.

By TechCompare · Updated

Topic
JWKS and kid
Key lookup
Category
Fundamentals
How JWTs are built and read

How this is calculated

OpenID Connect providers list their JWKS URL as jwks_uri in /.well-known/openid-configuration, so a verifier only needs the issuer's address. The kid is just a label. It lets the issuer rotate keys without breaking anything: it publishes a new key next to the old one, starts signing with it, and removes the old key after the last tokens signed with it have expired. Verifiers should cache the JWKS and refresh it when they see a kid they don't know, with a rate limit so random kids can't make them hammer the endpoint. A key in the set may carry alg, use and key_ops members. alg ties the key to one algorithm, use "sig" marks it for signatures, and key_ops can say "verify". A careful verifier respects all three. The token header can also carry jku (a JWKS URL), x5u (a certificate URL), jwk (a whole key) or x5c (a certificate chain). Those are dangerous to trust, because an attacker can point them at a key they control. The JWT Decoder accepts a pasted PEM key, a single JWK or a whole JWKS, picks the key by kid, refuses private keys, and never fetches or trusts a key from the token itself.

Verdict

Configure the issuer and its JWKS URL in your service, not in the token. Match by kid, check kty and alg, cache with a refresh on unknown kids, and keep the old key published for at least one token lifetime after rotation.

More JWT scenarios

Frequently asked questions

What is kid in a JWT header?
The key ID. It names which key in the issuer's JWKS signed the token, so the verifier can pick the right one during key rotation. It isn't secret and doesn't prove anything on its own.
How often should I fetch the JWKS?
Cache it, often for hours, and refresh when a token arrives with a kid you don't have. Rate limit those refreshes so a stream of fake kids can't overload the issuer or your service.
Can I paste a certificate instead of a public key?
Not into this tool. Extract the public key first with openssl x509 -pubkey -noout -in cert.pem, then paste the BEGIN PUBLIC KEY block it prints.