The Definitive Guide to JSON Web Tokens

A JSON Web Token (JWT) is an open industry standard (RFC 7519) method for representing claims securely between two parties. Unlike traditional opaque session cookies (where the server must look up the cookie ID in a database), a JWT contains all the necessary user data entirely within itself. It is stateless.

The Anatomy of a JWT

A JWT looks like a single string, but it consists of three distinct parts separated by dots (.): the Header, the Payload, and the Signature.

1. Header

Contains metadata about the token itself, primarily declaring what cryptographic algorithm was used to secure it (e.g., HS256 or RS256). It is merely Base64Url encoded JSON.

2. Payload

Contains the actual "claims" or statements about the user (like user ID, role, and expiration time). This is also just Base64Url encoded JSON—it is not encrypted.

3. Signature

The crucial security component. It is a cryptographic hash of the Header, the Payload, and a Secret Key known only to the server.

The Tampering Problem: Why Signatures Matter

Since the payload is just Base64Url encoded, anyone can decode it and read the contents. A malicious user might decode their token, see "role": "user", change it to "role": "admin", re-encode it, and send it back to the server.

Here's why that fails:

When the server receives the token, it takes the Header and the newly modified Payload, and runs them through the hashing algorithm using its private Secret Key. Because the Payload changed, the resulting Signature generated by the server will not match the signature provided on the token. The server instantly rejects the token as compromised.

System Design: JWTs vs Stateful Sessions

Stateful Sessions (Cookies)

The server drops an opaque string (e.g., session_id=fb829a...) in the user's browser. On every single API request, the server must query the database or Redis to ask, "Who does this ID belong to?"

✅ Server can instantly revoke access by deleting the row.
❌ Requires constant database lookups, harming scaling.
❌ Harder to share sessions across different microservices.

Stateless JWTs

The server parses the JWT algorithmically using CPU math (HMAC decoding). It never talks to the database. It trusts the data absolutely because the mathematical Signature is intact.

✅ Zero database lookups. Infinitely scalable microservice auth.
❌ Revocation is nearly impossible. You cannot "delete" a JWT until it naturally expires unless you introduce a stateful blocklist (defeating the purpose).

Advanced Concepts: Asymmetric Signing (RS256)

The simulator above uses HS256 (Symmetric Signing). This means the exact same Secret Key is used to both create the token and verify the token. This is dangerous in a microservice architecture, because every single service that needs to verify the token must be given a copy of the Secret Key. If one service is compromised, the attacker can forge tokens.

Modern enterprise systems use RS256 (Asymmetric Signing):

The central Authentication Server uses a heavily-guarded Private Key to generate and sign the JWTs.
All other microservices are given only a Public Key.
The Public Key can mathematically verify the signature was created by the Private Key, but the Public Key is fundamentally incapable of generating new valid JWTs.

JWT Lifecycle

Token Builder

Encoded Token

Signature Verified

Related Tools

Base64 Decoder

How OIDC Works