JSON Web Tokens

A signed JWT is three base64url parts joined by dots: header.payload.signature. The header and payload are just JSON anyone can read; the signature is the only part that needs a key, and it covers the first two parts exactly.

• Signed, not encrypted. The payload is public. Put an id and a few claims in it, never a password, card number or anything secret.
• The signature authenticates, it doesn't hide. It proves the token was made by someone with the key and hasn't changed since. Change one character of the payload and it no longer matches.
• HMAC vs public-key. HS256 uses one shared secret, so every service that can verify can also forge; RS256 and ES256 sign with a private key and verify with a public one, so verifiers never hold signing power. ES256 gives the same guarantee as RS256 in a far smaller token.
• Registered claims carry the rules: iss, sub, aud, exp, nbf, iat, jti. The header's alg and kid say how and with which key it was signed.

A JWT is only as safe as the code that verifies it. Almost every real-world JWT incident is a verifier that trusted the token too much — letting the token pick its own algorithm or key, or skipping a claim check. Here a naive verifier and a strict one face the same forged tokens.

• Pin the algorithm on the server. Never let the token's alg decide. This is what stops both alg: none and the classic RS256→HS256 key confusion, where a forger signs with the public key as an HMAC secret.
• Only trust keys you configured. Ignore jwk, jku and x5u in the header; look the key up by kid in your own set. A key the token brings is no key at all.
• Check the claims. A perfect signature says nothing about when or who for: always verify exp/nbf, iss and aud. A valid signature on a token meant for another API, or long expired, must still be rejected.
• Turn the strict verifier's checks off one at a time in the demo: each attack is let through by exactly one missing check.

A stateless token can't be called back, so the usual design is a short-lived access token (minutes) plus a long-lived refresh token that buys new ones. The hard parts are expiry, rotating refresh tokens safely, and actually revoking access.

• Keep access tokens short. exp is the main defence for a token that can't be revoked. Allow a few seconds of leeway for clock skew — seconds, not minutes.
• Rotate refresh tokens and detect reuse. Each refresh issues a new refresh token and retires the old one. If a retired one is ever presented again, treat it as theft and revoke the whole family — you can't tell the thief from the victim, so you log out both.
• Refresh tokens needn't be JWTs. An opaque random string stored server-side (as a hash) is easy to revoke and reveals nothing.
• Revocation needs state. To cut a valid access token off before exp you need a deny-list of token ids or a per-user token version checked on each request. With neither, a stolen access token works until it expires — which is the whole reason to keep it short.

Where a token lives in the browser decides who can steal it. The real trade-off is between XSS (a script running in your page) and CSRF (another site making requests as you) — each storage choice trades one risk for the other.

• localStorage / sessionStorage: any script on the page reads them, so an XSS bug exfiltrates the token outright. No cookie means no CSRF, but the exposure to XSS is the worst case.
• An HttpOnly cookie can't be read by JavaScript, so XSS can't steal the token — but the browser attaches it automatically, so you need SameSite (and CSRF defences) to control cross-site sends. Note XSS is still game over: a script can still make authenticated requests, it just can't take the token away.
• In memory (a variable, not storage) survives neither a reload nor XSS reading it — but a script can still patch fetch and ride along on the next call. Nothing in the page truly resists a script running in the page, which is why stopping XSS comes first.
• Sessions and the BFF. A plain server session (an opaque HttpOnly cookie, state on the server) is often the simplest safe choice for a first-party web app. A backend-for-frontend keeps the real tokens on the server and gives the browser only a session cookie — the browser never holds a JWT at all.

An issuer publishes its public keys as a key set (JWKS) and names the signing key in each token's kid. That lets verifiers find the right key, and lets the issuer rotate keys without downtime.

• Publish only public keys. A JWKS lists each key's public parts, its kid and its algorithm — never private material.
• Rotate by overlap. Add a new key and publish it; switch signing to it; keep verifying the old key until every token it signed has expired; then retire it. A token signed by a retired key fails with "unknown key id".
• Verify by kid, pinned to that key's algorithm. This is the same rule as the attacks topic: the key set, not the token, decides which algorithm is acceptable.