2026-07-24 · 6 min read · Rahul Chitturi
- jwt
- jwks
- incident-response
JWKS failures often look like ordinary authentication bugs until several services start returning 401 at once. A provider may rotate signing keys, a cache may hold stale metadata, or a proxy may block the JSON Web Key Set endpoint.
A runbook keeps responders from guessing. It separates token evidence, issuer metadata, key cache behavior, and verifier configuration so the team can identify whether the outage lives in the identity provider, network path, or application code.
Collect safe evidence first
Use a non-production token or a masked production fixture that preserves the header, issuer, audience, algorithm, and key ID. Never paste live user tokens into tickets or shared chats.
- Decode the JWT header and payload, then verify signatures only in trusted server-side tooling
- Compare the token kid against the current JWKS document
- Record cache TTL, last refresh time, and forced-refresh behavior
- Check issuer discovery URLs and any proxy, firewall, or DNS dependency in the path
Decide when to refresh or rollback
If the key exists in JWKS but the service still rejects tokens, inspect cache age and verifier configuration. If the key is missing from JWKS, treat the identity provider or environment config as the primary suspect before changing application authorization logic.
For PEM or environment variable based fallbacks, validate newline handling separately. A copied public key with escaped newlines can create the same invalid signature symptom as a real JWKS problem.
A Flashman workflow
Use the JWT decoder for safe fixtures, the JSON formatter for JWKS documents, the PEM newline helper for fallback keys, and the diff tool to compare working and failing issuer metadata snapshots.