JWKS & JWT Signature Verifier

A JSON Web Key Set (JWKS) is a JSON document that publishes the public keys an identity provider uses to sign its tokens. Each entry in the keys array is a JSON Web Key (JWK) describing one key: its type (kty), intended use (use: "sig"), algorithm (alg), and a key ID (kid).

Keycloak serves its JWKS at /realms/<realm>/protocol/openid-connect/certs, and any client can fetch it to verify tokens without ever seeing a private key. That is the whole point: the signing key stays secret on the server, while the verification key is public by design.

For a deeper walkthrough of the format and how rotation works, read our guide to understanding JWKS (JSON Web Key Sets).

Every signed JWT carries a kid (key ID) in its header. Verification uses it as a lookup:

1. Read the header: the verifier decodes the JWT header and reads the kid and alg values.
2. Find the key: it scans the JWKS for a key whose kid matches, then imports that public key.
3. Verify: it checks the signature over the header and payload with that key. Any other key in the set is irrelevant.

The kid is what makes key rotation seamless: an identity provider can publish the new key alongside the old one, and tokens signed by either keep verifying until the old key is retired. This tool shows you the match status explicitly, and falls back to trying every signing key when the kid is missing or unmatched.

Decoding a JWT is not verification. Anyone can mint a token with any claims they like: admin: true, your user's email, a fresh expiry. The only thing that ties a token to your identity provider is the signature, so a backend that trusts decoded claims without verifying them is effectively unauthenticated.

If you only need to inspect a token's contents, our JWT Token Analyzer does that. This tool goes one step further and answers the question that matters in production: was this token really signed by the key set you trust?

In your own services, do this check on every request with a proper JWT library. Our guide to verifying a Keycloak-issued access token on the backend walks through the full server-side flow, including JWKS caching and issuer checks.

When a signature check fails against keys you believe are correct, it is usually one of these:

• kid mismatch after rotation: the realm rotated its signing key and the token was issued by a key that is no longer (or not yet) in the set you fetched.
• Stale JWKS cache: your backend cached the JWKS before a rotation and never refetched. Verifying against a freshly fetched set here but failing in production is the classic symptom.
• Wrong realm URL: fetching the JWKS from the master realm while the token was issued by another realm. Compare the token's iss claim with the realm in your JWKS URL.
• Clock skew: a token that is valid cryptographically but rejected on exp or nbf because the issuer and verifier disagree on the time. Allow a small skew window.