How JWT (JSON Web Token) Works — Structure, Signing, Verification Explained

Core Concepts

Three-part structure (header.payload.signature)

Every JWT is three Base64URL-encoded segments separated by dots. The header declares the algorithm (alg) and key ID (kid). The payload carries claims — standardized ones like exp (expiry), iat (issued-at), iss (issuer), aud (audience), and custom ones like user_id or role. The signature prevents tampering: changing a single byte in the payload invalidates it.

Symmetric vs asymmetric signing

HS256 (HMAC + SHA-256) uses a shared secret — both the signer and the verifier know the same string. RS256 (RSA) and ES256 (ECDSA) use a private key to sign and a public key to verify. Asymmetric keys let you safely publish the public key (e.g. at /.well-known/jwks.json) without exposing the signing secret. Pro tip: never use HS256 across service boundaries; if anyone on either side leaks the secret, they can forge tokens for every user.

Claims — exp, iat, nbf, aud, iss, sub

exp (expires-at) is the most critical: a Unix timestamp after which the token should be rejected. iat (issued-at) helps detect token replay. nbf (not-before) defers validity to a future time. aud (audience) restricts the token to a specific API. iss (issuer) identifies who minted it. sub (subject) is the user or resource the token represents. Claim validation is separate from signature validation — a perfectly-signed token can still be invalid if the claims don't check out.

The alg=none attack

Some older JWT libraries accepted tokens whose header claimed alg: 'none' (unsigned). An attacker can strip the signature, change the payload, and the server would trust it. Modern libraries reject alg: none by default, but explicit algorithm allowlisting (algorithms: ['RS256']) is the definitive defense — it prevents algorithm-confusion attacks where an RS256 public key gets reused as an HMAC secret.

JWKS (JSON Web Key Set)

A public endpoint (/.well-known/jwks.json) that lists an issuer's public keys, each with a kid. Verifiers fetch this set, pick the key whose kid matches the token header, and verify the signature. Key rotation works by adding a new key alongside the old one in the set — old tokens validate against the old key until they expire.

Frequently Asked Questions