- Publish a new public key in the trusted JWKS before the signer starts using its
kid. - Make verifiers accept multiple current keys and refresh the issuer's known
jwks_uriwhen an unfamiliar key ID appears. - Remove the old public key only after the routine overlap covers accepted token lifetimes and verifier cache behavior; treat a suspected compromise as a different incident.
A signing-key rotation can fail even when the new key is correct. One API still has the old key cached. Another receives a token with a kid it has never seen. Valid users get rejected in waves.
The safe pattern is an overlap, not a swap. Publish the new public key, let verifiers learn it, start signing with it, then keep the old public key long enough to validate tokens that were already issued.
That order is the key.
Keep the scope precise
This workflow covers asymmetric keys used to sign JWTs in an OpenID Connect-style deployment. The issuer holds a private signing key. Verifiers receive public keys from a JSON Web Key Set, or JWKS.
It is not a guide to rotating encryption keys. It also does not make a shared HMAC secret public. Symmetric signing needs a different distribution and rollover plan because the verifier holds secret material.
OpenID Connect discovery gives the verifier a trusted jwks_uri. The JWT header can carry a kid that selects one candidate from that key set. A key ID is a selector, not proof that the token is safe.
| Stage | Issuer action | Verifier proof |
|---|---|---|
| Prepare | Generate a protected private key and distinct kid | Old path still works |
| Publish | Add the new public JWK; keep signing with old | JWKS refresh sees both keys |
| Switch | Sign new tokens with the new key ID | Representative services accept new and old tokens |
| Retire | Stop using old private key for new tokens | Old public key remains for the overlap |
| Remove | Delete old public JWK after the safe window | No accepted token or cache still needs it |
Name one owner for the change. Record each key ID, switch time and rollback step. Keep the log with the issuer runbook.
Publish before you sign
Generate the new private key inside the approved key store. Give its public JWK a distinct, unpredictable identifier. RFC 7517 says keys in one set should use distinct kid values.
Add only the public material to the JWKS. Private and symmetric key values must be protected from unintended disclosure.
Keep using the old key. Fetch the discovery document and JWKS from outside the issuer control plane. Check the cache headers. Make sure each main verifier can load more than one key.
Switch signing while both public keys remain
After the new JWK is available, change the active signer. New tokens should name the new kid. Tokens already signed with the old private key may remain valid until their normal acceptance window ends.
OpenID Connect Core says a verifier that sees an unfamiliar signing key ID can retrieve the keys again. It also says the JWKS should keep recently decommissioned signing keys for a reasonable period to smooth the transition.
Use a maintained protocol library where possible. Microsoft’s identity guidance makes the same operational point: verifiers must handle several keys and sudden rollovers instead of hard-coding one certificate.
Refresh safely on an unknown key ID
Fetch keys only from the trusted issuer metadata path. Do not turn a token-supplied URL into a network request, and do not accept a token just because its kid matches something.
After key selection, verify the signature with an allowed algorithm. Then validate the issuer, audience, token type and time claims required by your protocol. RFC 8725 treats algorithm, issuer and audience checks as separate security requirements.
Rate-limit forced refreshes. An attacker can send many random key IDs and cause a fetch storm. Preserve the last valid key set according to your library and issuer policy, but never convert a JWKS outage into “accept without verification.”
Calculate the removal window from real behavior
There is no universal safe number of hours. List the longest token lifetime that your verifier still accepts, clock-skew allowance, queue or offline delay, and JWKS cache behavior. Use the largest relevant window, then add an explicit operational margin.
Measure each consumer. Gateways, background workers, mobile backends and partner services may refresh keys differently. The software support calendar offers a way to record owners and versions for these hidden dependencies.
Stop using the old private key. Keeping the old public key available does not allow anyone to mint a token. It only lets verifiers check tokens that already carry a valid old signature.
Test routine rotation and emergency response separately
- Issue a canary with the new key. Verify it in each major runtime and gateway.
- Keep an old-token canary: confirm it still works during the planned overlap.
- Send an unknown key ID. Confirm one managed refresh occurs and the invalid token is rejected.
- Exercise JWKS failure. Check documented cache behavior without weakening signature checks.
- Remove the old public key in a test issuer. Confirm the expected old token stops working.
A suspected private-key compromise changes the tradeoff. Fast removal can reject valid sessions, but a long overlap can extend trust in an exposed signer. Follow the issuer's incident procedure, consider token or session revocation controls, and use the emergency access drill before a real event.
Key rotation also does not stop a stolen bearer token. The device-bound session guide explains that separate risk. These are procedures to test; TechWeb did not rotate your issuer keys or validate your tokens.
Frequently asked questions
Should a JWKS contain the private signing key?
No. A public JWKS used by verifiers must expose only the public material needed for verification.
Can a verifier trust a token because the kid matches?
No. It must still verify the signature and required algorithm, issuer, audience, type and time claims.
How long should the old public key remain?
Long enough for accepted old tokens and relevant verifier caches to age out, plus the margin set by your policy. The exact window is deployment-specific.
Is emergency rotation the same as routine rotation?
No. A suspected private-key compromise may justify a shorter overlap and forced session impact. Use the issuer's incident and revocation controls.
Sources
OpenID Connect Core 1.0: Rotation of Asymmetric Signing Keys · IETF RFC 7517: JSON Web Key · IETF RFC 8725: JWT Best Current Practices · IETF RFC 8414: Authorization Server Metadata · Microsoft: Signing key rollover. Library and issuer behavior can change; verify the versions and cache policy you run.
More in this sectionTechnology →