Spring Resource Server JWT key rotation: overlap keys across token lifetime

A kid is a lookup hint

A signed JWT carries a key identifier that helps the decoder choose a public key from the issuer's JWK set. The signature still has to verify; a kid is not proof of trust. Spring Resource Server can obtain and refresh JWK data from the configured issuer. Keep the issuer and accepted algorithm policy deliberate, and retain issuer, audience and time validation alongside signature checks. If the application supplies its own JwtDecoder bean, configure validators explicitly and test a token from the wrong issuer; do not assume a builder method installed those validators.

Roll in two directions

First publish the new public key while still signing with the old private key. Wait for verifiers to fetch the new set, then begin signing new tokens. Keep the old public key until every old token can expire plus any relevant cache window. If the issuer drops it immediately, valid tokens can fail during rollout. If a compromised private key must be revoked immediately, accepting some old tokens is no longer safe; plan for an explicit user reauthentication event.

Test the outage path

Run a verifier against a controlled JWK endpoint: accept a token signed with the old key, add the new key, accept a new token, then remove the old key after its expiry window. Test an unknown kid while the endpoint is unavailable and inspect the chosen decoder's cache behavior. Do not assume every node refreshes at the same instant. Authentication failure mapping should distinguish bad credentials from a resource outage in logs without leaking key details to callers.

Implementation contract

spring.security.oauth2.resourceserver.jwt.issuer-uri=${JWT_ISSUER}

Cost and verification

JWK retrieval and cache misses add network and parse work. An overly short cache can overload the issuer; an overly long cache can delay planned rotation or emergency revocation. Measure the verifier's actual refresh behavior under load.

Common Mistakes

• Do not remove the old public key as soon as new signing begins.
• Do not accept a token merely because its kid matches a published key.
• Do not assume a custom JwtDecoder carries issuer and audience validators unless you configured and tested them.

Read next

Spring resource server JWT: validate both issuer and intended audience, Spring Security JWT resource server: validate trust before checking scope, Spring Security 401 versus 403: authentication and access are separate failures, Test Spring JWT authorization through filters, service proxy and SQL, Spring Security filter chain: authentication, CSRF and request order.