Demystifying JSON Web Tokens (JWT): Architecture, Security Best Practices & Debugging
Deep dive into JSON Web Tokens (RFC 7519). Learn how headers, payloads, and cryptographic signatures interact, prevent critical vulnerabilities like alg:none, and implement secure token refresh flows.
JWT Decoder & Security Inspector
Decode, inspect claims, verify expiry timestamps, and validate signatures client-side.
What is a JSON Web Token (JWT)?
Defined in RFC 7519, a JSON Web Token (JWT) is a compact, URL-safe, self-contained standard for securely transmitting information between two parties as a JSON object. Because JWTs are cryptographically signed, the recipient can independently verify the token's authenticity, integrity, and sender identity without making a database lookup on every incoming HTTP request.
JWTs are the de facto standard in modern architectures:
The Anatomy of a JWT: Three Parts Separated by Dots
A standard serialized JWT looks like a string of base64url characters broken into three segments by periods (.):
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkFsZXgiLCJyb2xlIjoiYWRtaW4iLCJleHAiOjE3NjgwMDAwMDB9.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk1. Header
The header typically consists of two fields: the signing algorithm used (alg, e.g., HS256, RS256, ES384) and the token type (typ: "JWT").
{
"alg": "HS256",
"typ": "JWT"
}2. Payload (Claims)
The payload contains the claims—statements regarding an entity (usually the user) and contextual metadata. Claims fall into three categories:iss (issuer), sub (subject), aud (audience), exp (expiration time in Unix seconds), nbf (not before), and iat (issued at).{
"sub": "usr_998124",
"name": "Sarah Connor",
"role": "editor",
"tenant_id": "org_cyberdyne",
"iat": 1726000000,
"exp": 1726003600
}> CRITICAL SECURITY NOTE: The payload is encoded, not encrypted! Anyone with access to the raw token string can decode the Base64URL string to read all payload contents. Never store sensitive credentials, plaintext passwords, credit card numbers, or private API keys inside a JWT payload unless you use JWE (JSON Web Encryption).
3. Signature
The signature is generated by running the encoded header, the encoded payload, a secret key, and the specified algorithm through a cryptographic hashing function:HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secretKey
)If an attacker modifies even a single character of the payload (e.g., changing "role": "user" to "role": "admin"), the signature verification mathematically fails, and the server rejects the request.
Symmetric (HMAC) vs. Asymmetric (RSA/ECDSA) Signing
| Feature | Symmetric (HS256 / HS384 / HS512) | Asymmetric (RS256 / ES256 / EdDSA) |
|---|---|---|
| Keys Required | Single shared secret (e.g., a long random string) | Key Pair: Private Key (sign) & Public Key (verify) |
| Trust Model | Every service verifying the token must know the secret | Only the Auth Server knows the Private Key; all microservices verify using the Public Key |
| Risk Profile | If one microservice is breached, the secret leaks and attacker can forge tokens | If a consumer service is breached, only the Public Key is exposed; no tokens can be forged |
| Best Used For | Monoliths or single private backend APIs | Distributed microservices, OAuth2, OIDC, public-facing APIs |
Top 4 Common JWT Security Pitfalls & Vulnerabilities
1. The Notorious "alg: none" Exploit
In early implementations of several popular JWT libraries, setting"alg": "none" in the header caused the parser to accept tokens without checking any signature whatsoever. Attackers could craft an arbitrary payload with administrative rights, remove the signature, and gain full root access.
algorithms: ['RS256']). Never trust the incoming token's header to determine verification logic.2. Weak HMAC Shared Secrets
If your secret is short or dictionary-based (like"supersecret" or "my-jwt-token"), tools like hashcat can brute-force 100 million passwords per second on modern consumer GPUs and extract your signing key within seconds.
crypto.randomBytes(32)).3. Storing JWTs in Browser LocalStorage
Placing authentication tokens inlocalStorage makes them vulnerable to Cross-Site Scripting (XSS). Any malicious third-party script or compromised npm package running on the page can execute localStorage.getItem('token') and exfiltrate user credentials.
HttpOnly, SameSite=Strict, Secure HTTP cookies.4. Excessive Token Expiry Times
Tokens with multi-day expiration periods cannot be revoked easily without maintaining an expensive blacklist database (which defeats the point of stateless tokens).Inspecting & Debugging Tokens Safely
When troubleshooting authorization bugs, copying a live production token into random third-party websites can leak user data or access keys to untrusted servers.
Our client-side JWT Decoder & Inspector operates 100% inside your local browser sandbox. Nothing is transmitted over the wire, allowing you to safely inspect claims, verify expiration countdowns, and validate signatures with complete confidentiality.
Editorial Integrity & Peer Review
All technical guides on MicroTools are independently authored and peer-reviewed by software and infrastructure professionals. Content is updated periodically to ensure compliance with the latest IETF RFC specifications, IEEE standards, and cloud provider architectural recommendations.