Mastering JSON Web Tokens (JWT): Security Best Practices, Claims & Decoding Guide
Master JSON Web Token (JWT) structure, claims validation, security vulnerabilities, and decoding techniques. Learn header, payload, and signature parsing with free developer tools.
In modern REST APIs, microservices, and single-page web applications (SPAs), JSON Web Tokens (JWTs) have become the standard RFC 7519 open specification for compact, self-contained claims transmission between two parties. Unlike traditional session cookies stored in server memory or Redis caches, JWTs are stateless—all authorization claims, user identity data, and expiration dates are encoded directly inside the token string.
When a user logs in via OAuth 2.0 or OpenID Connect (OIDC), the identity provider signs a JWT and returns it to the client. The client attaches this token in the HTTP Authorization header (as a Bearer token) for subsequent API calls, allowing backend microservices to authenticate requests instantly without performing expensive database lookups.
1. What is a JSON Web Token (JWT) and How Does It Work?
A standard JWT consists of three distinct base64url-encoded strings separated by dots (.): Header.Payload.Signature. Understanding each component is essential for building secure authentication systems.
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c2. The Three Parts of a JWT: Header, Payload & Signature
| Part | Name | Encoded Format | Decoded JSON Contents & Purpose |
|---|---|---|---|
| Part 1 | Header | Base64URL | Specifies the signing algorithm (e.g. HS256, RS256) and token type (JWT). |
| Part 2 | Payload | Base64URL | Contains reserved claims (sub, exp, iat) and custom user claims (email, roles). |
| Part 3 | Signature | Cryptographic Hash | Generated using algorithm + secret key to prevent token tampering. |
3. Standard JWT Reserved Claims vs Custom Claims
Claims are statements about an entity (typically the authenticated user) and additional metadata. RFC 7519 defines seven standard reserved claims.
| Claim Key | Full Claim Name | Data Type | Standard Purpose & Behavior |
|---|---|---|---|
| iss | Issuer | String / URL | Identifies the authentication service or URL that issued the token. |
| sub | Subject | String | Unique user ID or entity identifier for whom the claims are made. |
| aud | Audience | String / Array | Identifies the target recipient or API service that should accept the token. |
| exp | Expiration Time | Unix Timestamp | Identifies the exact expiration timestamp after which the token is invalid. |
| nbf | Not Before | Unix Timestamp | Identifies the timestamp before which the token must not be accepted. |
| iat | Issued At | Unix Timestamp | Identifies the exact timestamp when the token was created. |
| jti | JWT ID | String (UUID) | Unique identifier for the token; used to prevent replay attacks. |
4. Symmetric (HS256) vs Asymmetric (RS256/ES256) Signing
| Algorithm | Encryption Type | Keys Used | Best Use Case |
|---|---|---|---|
| HS256 (HMAC + SHA256) | Symmetric | Single shared secret key | Monolithic apps & internal microservices where server shares secret. |
| RS256 (RSA + SHA256) | Asymmetric | Private key (Sign) / Public key (Verify) | OAuth 2.0 / OIDC identity providers with third-party consumers. |
| ES256 (ECDSA + P-256) | Asymmetric | Elliptic Curve key pair | High-performance microservices requiring smaller signature size. |
5. Step-by-Step Guide: Decoding and Validating JWTs in Code
Decoding a JWT allows you to read header and payload claims. However, decoding alone does NOT verify security unless signature validation is performed!
// Node.js / JavaScript JWT Decoding & Verification
const jwt = require('jsonwebtoken');
const token = 'eyJhbGciOiJIUzI1Ni...';
const secretKey = process.env.JWT_SECRET;
try {
// Verifies signature AND checks exp / nbf claims
const decoded = jwt.verify(token, secretKey);
console.log('Authenticated User:', decoded.sub);
} catch (err) {
console.error('Invalid or Expired Token:', err.message);
}6. 5 Critical Security Vulnerabilities & Prevention
- The 'alg: none' Attack: Malicious actors modify the header algorithm to 'none' to strip signature checks. Fix: Always enforce explicit algorithm whitelist in backend verifiers.
- Weak HMAC Secret Keys: Using weak passphrases like 'secret' allows offline brute-forcing with hashcat. Fix: Use high-entropy 256-bit random keys.
- Storing JWTs in LocalStorage: LocalStorage is vulnerable to Cross-Site Scripting (XSS) theft. Fix: Store access tokens in HttpOnly, SameSite cookies.
- Long-Lived Tokens Without Expiration: Missing exp claims allow stolen tokens to work indefinitely. Fix: Set short access token TTLs (15 mins) with refresh tokens.
- Algorithm Confusion (RS256 to HS256): Attackers use public RSA keys as HMAC secret keys to sign forged tokens. Fix: Restrict verification algorithms.
7. Frequently Asked Questions (FAQs)
What is the difference between base64 decoding and signature verification?
Base64 decoding exposes readable JSON text in header and payload. Signature verification uses cryptography to guarantee that the content was not altered.
Can someone edit the payload of a JWT?
Anyone can edit the base64 string, but doing so invalidates the signature, causing backend API verification to fail immediately.
Where should I store JWTs on the client side?
Store short-lived access tokens in HttpOnly, Secure, SameSite cookies to protect against XSS and CSRF attacks.
What does exp claim mean?
The exp claim defines the exact Unix epoch timestamp when the token expires and becomes invalid.
How do I decode a JWT online securely?
Use the free Tools QuizOxa JWT Decoder tool which runs 100% locally in your browser with zero server transmission.
8. Key Takeaways for JWT Security
- JWTs are readable by anyone because they are base64url encoded; never store sensitive secrets (passwords, SSNs) inside payload claims.
- Always validate signature, iss, aud, and exp claims on every incoming API request.
- Use the free Tools QuizOxa JWT Decoder tool for instant token debugging.
Need to inspect a token payload or debug claims? Use the Free Tools QuizOxa JWT Decoder to parse, inspect, and format JWTs securely in your browser.