JSON Web Tokens (JWTs) are a compact, self-contained format for representing claims between two parties. In web authentication, a server issues a JWT when a user logs in, and the client sends that token with every subsequent request so the server can verify the user's identity without querying a database. Understanding how JWTs work — and where they can go wrong — is essential for building secure applications.
The Three Parts of a JWT
A JWT consists of three Base64url-encoded parts separated by dots: header.payload.signature. The header specifies the token type (JWT) and the signing algorithm (typically HS256 or RS256). The payload contains claims — key-value pairs that assert facts about the user, such as their user ID, email, roles, and the token's expiration time. The signature is computed over the header and payload using a secret key, and it is what allows the recipient to verify that the token has not been tampered with.
- Header: algorithm and token type, Base64url-encoded JSON.
- Payload: claims (sub, iat, exp, custom fields), Base64url-encoded JSON.
- Signature: HMAC-SHA256 or RSA signature over header.payload, using the server's secret.
How Verification Works
When a server receives a JWT, it splits the token at the dots, decodes the header to determine the algorithm, then recomputes the signature over the received header and payload using the server's secret key. If the computed signature matches the received signature, the token is valid and the payload can be trusted. If even one character of the header or payload was changed after signing, the signature will not match and the token is rejected.
This is why JWTs are called stateless — the server does not store sessions. The signed payload carries all the information the server needs, and the signature guarantees it has not been modified. There is no database lookup on every request.
Common JWT Claims
- sub (subject): the user's unique identifier.
- iat (issued at): Unix timestamp when the token was issued.
- exp (expiration): Unix timestamp after which the token is invalid.
- iss (issuer): the server that issued the token.
- aud (audience): the intended recipient of the token.
- Custom claims: roles, permissions, email — anything the application needs.
Security Concerns
The algorithm confusion attack exploits servers that accept any algorithm specified in the token header. An attacker changes the header from RS256 (asymmetric) to HS256 (symmetric) and signs the token with the server's public key, which is publicly known. If the server naively uses the algorithm from the header, it verifies the signature using the public key as the HMAC secret and accepts the forged token. The fix is to never trust the algorithm field from the token — always verify with a hard-coded expected algorithm.
JWTs cannot be invalidated before they expire without maintaining a server-side blocklist, which partially defeats the stateless benefit. For this reason, keep JWT lifetimes short (15 minutes for access tokens) and use refresh tokens with longer lifetimes that can be stored server-side and revoked. Store JWTs in httpOnly cookies, not localStorage, to prevent JavaScript access and reduce XSS exposure.