Understanding JSON Web Tokens (JWT): Structure, Verification, and Common Pitfalls.
An exhaustive technical breakdown of JWT architecture (RFC 7519), signing algorithms (HMAC vs RSA/ECDSA), and cryptographic security best practices.
1. What Is a JSON Web Token?
Defined in RFC 7519, a JSON Web Token (JWT) is a compact, URL-safe means of transferring claims between two parties. Unlike stateful session architectures where a server maintains active session records in memory or Redis, JWTs are typically stateless: the token itself encapsulates all authorization claims, signed cryptographically to prevent tampering.
A standard JWT appears as a compact string of characters separated by two period delimiters (.), representing three distinct sections:
2. Deconstructing the Three Sections
Section 1: The Header (Rose)
Specifies token metadata, primarily the token type ("typ": "JWT") and the cryptographic signing algorithm ("alg": "HS256", "RS256", etc.). The JSON string is serialized to Base64URL encoding.
Section 2: The Payload / Claims (Violet)
Contains the factual claims. Standard registered claims include:
sub(Subject): Unique user identifier.iss(Issuer): Identification of the authentication authority.exp(Expiration Time): Unix timestamp indicating token validity deadline.iat(Issued At): Timestamp when the token was created.
Section 3: The Cryptographic Signature (Cyan)
Generated by taking the encoded header, encoded payload, and signing them against a secret key or private key. If an attacker modifies even a single character in the header or payload, the mathematical signature verification will fail instantly.
3. Symmetric (HS256) vs Asymmetric (RS256 / ES256)
| Algorithm | Key Type | Best Use Case | Security Consideration |
|---|---|---|---|
| HMAC-SHA256 (HS256) | Single shared secret | Internal microservices with shared trust | Any server verifying the token can also forge tokens if compromised |
| RSA-SHA256 (RS256) | Public / Private keypair | Public OAuth/OpenID Connect identity providers | Auth server signs with private key; any service verifies with public key |
4. Common Security Anti-Patterns
- The 'None' Algorithm Vulnerability: Early JWT libraries allowed the header
{"alg": "none"}, causing the parser to treat unsigned tokens as valid. Modern libraries strictly forbid unsigned tokens unless explicitly configured. - Storing Sensitive Data in Payloads: A JWT is signed, NOT encrypted. Anyone who intercepts the token can decode the Base64 payload in seconds. Never place passwords, credit card numbers, or proprietary API keys inside JWT claims.
- Neglecting Expiration (exp): Stateless tokens cannot be revoked easily without an expensive server-side blocklist. Keep access token lifetimes short (e.g., 10–15 minutes) paired with secure HTTP-only refresh tokens.
Need to inspect a token's header and claims quickly? Use our safe, in-browser JWT Decoder Tool or generate test authorization headers with our JWT Generator.