Understanding JWT Tokens: Structure, Cryptography, and Security Best Practices
A deep-dive engineering guide into JSON Web Tokens (JWT), header/payload/signature mechanics, cryptographic validation algorithms, and common security pitfalls.
Dhaval Joshi
Lead Systems Architect at FreeToolkit
Table of Contents
In modern stateless microservices, Single Page Applications (SPAs), and mobile backends, JSON Web Tokens (JWT) specified by RFC 7519 have become the universal currency for decentralized authentication and identity exchange. However, misunderstanding JWT encryption, token verification, or client-side storage opens catastrophic attack vectors.
What is a JSON Web Token (RFC 7519)?
A JSON Web Token is an open, industry-standard RFC method for representing claims securely between two parties. Unlike legacy session identifiers stored in centralized Redis caches or database tables, a JWT is completely self-contained. The token itself carries the user identifier, assigned roles, permissions, and cryptographic signature required for an API gateway to grant access without querying a database.
The Anatomy of a JWT: Three Encoded Parts
In its serialized form, a JWT consists of three distinct Base64URL-encoded strings separated by dot (.) characters:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkRoYXZhbCBKb3NoaSIsImlhdCI6MTUxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c1. Header (Red)
Defines token metadata, typically the signing algorithm (e.g., HS256, RS256) and the token type (JWT).
{ "alg": "HS256", "typ": "JWT" }
2. Payload / Claims (Purple)
Contains claims—statements about the user and additional context. Standard registered claims include sub (subject), exp (expiration timestamp), iat (issued at), and iss (issuer).
{ "sub": "usr_9481a", "role": "admin", "exp": 1757239800 }
3. Signature (Blue)
Generated by hashing the encoded header, dot, and encoded payload against a secret cryptographic key. Guarantees message integrity—if any claim in the payload is altered, the signature verification fails instantly.
Critical Insight: JWT is Signed, NOT Encrypted!
Base64URL encoding is trivial to reverse. Never store sensitive credentials, plaintext passwords, credit card numbers, or PII inside a standard JWS token payload, because any party holding the token can decode it in milliseconds.
Symmetric vs Asymmetric Signing (HS256 vs RS256)
- HS256 (HMAC with SHA-256): Symmetric encryption. The identical secret key is used by the authentication server to issue tokens and by every microservice to verify them. Ideal for monolithic applications or internal clusters where the secret never leaves a secure perimeter.
- RS256 / ES256 (RSA / ECDSA): Asymmetric cryptography. The auth server signs tokens using a strictly guarded Private Key. Any microservice, third-party client, or mobile app can verify the signature using the publicly distributed Public Key (often hosted on a
/.well-known/jwks.jsonendpoint).
Critical Security Vulnerabilities to Avoid
- The 'None' Algorithm Attack: Early parser libraries allowed attackers to set
"alg": "none"and strip the signature entirely. Modern libraries must strictly whitelist allowable algorithms. - Key Confusion Attacks: Forcing an asymmetric RS256 server to verify a token using HS256, treating the public RSA key string as an HMAC symmetric secret.
- Missing Expiration Checks: Always enforce tight expiration (
exp) windows—typically 10 to 15 minutes for access tokens paired with rotating refresh tokens.
Token Storage: HttpOnly Cookies vs LocalStorage
Storing tokens in browser localStorage leaves them vulnerable to Cross-Site Scripting (XSS) injection attacks where any malicious dependency or script tag can read localStorage.getItem('token').
The recommended industry standard is storing refresh tokens in an HttpOnly, Secure, SameSite=Strict cookie, preventing JavaScript execution access entirely while transmitting tokens automatically on authenticated requests.
Related Free Online Tools
About Dhaval Joshi
Lead Systems Architect at FreeToolkit
Dhaval designs and maintains FreeToolkit’s browser-native processing engines, WebAssembly pipelines, and zero-knowledge privacy architectures. Passionate about web performance, cryptographic systems, and open-source tooling.