Why JWT security matters
json Web Tokens (JWTs) are a compact, url-safe way to represent claims between parties. They are used for authentication, authorization, and conveying small pieces of identity-related information. Because a JWT can be self-contained and verified without a server-side lookup, mistakes in how it is created, stored, or validated can lead to serious vulnerabilities. Understanding the security properties of signing, encryption, storage, expiration, and revocation is essential for using JWTs safely in web and mobile systems.
How JWTs work at a glance
A JWT has three parts separated by dots: header, payload, and signature. The header declares the algorithm (for example, HS256 or RS256) and optional metadata; the payload contains claims such as issuer (iss), subject (sub), audience (aud), expiration (exp) and custom fields; the signature (or MAC) proves integrity. These parts are Base64URL-encoded. There are two related standards: JWS (JSON Web Signature) for signing and JWE (JSON Web Encryption) for encrypting. Signing ensures the token hasn’t been tampered with, while encryption hides the payload contents.
Signing vs encryption
Many implementations only sign tokens (JWS), relying on the signature to prove authenticity while leaving the payload readable. If the payload contains personal or sensitive data, sign-and-send is not enough,use JWE to encrypt the token or avoid placing secrets in the token at all. For most authentication flows, signing with a strong algorithm and short lifetime for access tokens is adequate, while refresh tokens (which grant longer-lived access) should be protected more carefully or stored server-side.
Common pitfalls and attacks
Several recurring mistakes cause vulnerabilities with JWTs. One historic example is the “alg=none” attack, where a server mistakenly accepts unsigned tokens. Another class of problem is algorithm confusion, when code trusts the token’s header to choose verification behavior rather than enforcing expected algorithms. Holding signing keys in source code, using weak symmetric secrets (e.g., short HS256 keys), storing tokens insecurely in browser localStorage, or exposing long-lived tokens without a revocation mechanism all increase risk. Cross-site scripting (XSS) and cross-site request forgery (CSRF) remain major threats to tokens stored in the browser unless mitigations are in place.
Key specific issues
- Accepting unverified algorithm headers or the “none” algorithm.
- Using weak secret keys or reusing symmetric keys across services without rotation.
- Persisting sensitive payload data inside tokens (they are not encrypted unless JWE is used).
- Long-lived access tokens without refresh-rotation or server-side revocation.
- Storing tokens in places vulnerable to XSS (localStorage) or missing CSRF defenses when using cookies.
Best practices for secure JWT use
Applying a set of defensive measures will greatly reduce the chance of problems. These practices fall into categories: token construction, validation, storage, and lifecycle management. At token construction, prefer strong algorithms such as RS256 or ES256 for distributed systems, and enforce an algorithm whitelist on the server rather than trusting incoming headers. Use minimal claims and avoid putting secrets or private data inside the payload unless the token is encrypted with JWE.
For validation, always verify the signature, check exp (expiration) and nbf (not before), confirm iss (issuer) and aud (audience) match expected values, and allow a small clock skew for distributed systems. Implement proper error handling that does not leak sensitive implementation details.
On storage and transfer, always use tls; prefer HttpOnly, Secure cookies with SameSite settings for browser-based sessions if you need protection from XSS and want to manage CSRF separately. If you store tokens in single-page apps, understand that localStorage is vulnerable to XSS; mitigate XSS with CSP, input sanitization and secure frameworks. For mobile apps, use platform secure storage (e.g., Keychain, Android Keystore).
Recommended checklist
- Use TLS everywhere for token transport.
- Choose strong signing algorithms (RS256/ES256) and validate algorithm explicitly.
- Keep access token lifetimes short and use refresh tokens for session renewal.
- Store tokens in Secure, HttpOnly cookies for browser apps when possible and implement CSRF controls.
- Do not place sensitive personal data in the token unless encrypted (JWE).
- Maintain key rotation and a revocation strategy (see below).
Managing token lifecycle and revocation
Stateless JWTs are attractive because they remove server-side lookups, but that makes revocation harder. You can address revocation with a few patterns: keep access tokens short and use refresh tokens that can be revoked, maintain a server-side blacklist of revoked token IDs (jti) or session identifiers, or use opaque tokens for access and perform token introspection against an authorization server. Refresh token rotation with reuse detection provides a balance between usability and security: when a refresh token is used, issue a new one and invalidate the used token; if an old token appears after rotation, flag possible theft and revoke the session.
Key rotation
Rotate keys periodically and expose public keys via a JWKS endpoint if you use asymmetric signing. Include a key id (kid) in the header so verifiers can find the correct key. During rotation, keep previous keys available to verify still-valid tokens until they expire, and have an automated process to retire old keys after a safe overlap period.
Practical recommendations for common architectures
For microservices where many components must verify tokens, use RS256 or ES256 with a central JWKS endpoint so services can verify signatures without sharing private keys. For simple internal applications, HS256 with a strong secret can be acceptable if the secret is rotated and stored securely, but asymmetric keys are generally safer when multiple systems are involved. When mitigating client risks, treat a browser session cookie with HttpOnly and SameSite as the default for interactive logins, and reserve tokens sent to APIs for short-lived access tokens acquired via secure flows.
When to choose encrypted tokens (JWE)
Choose JWE if the token will travel through systems that should not see the payload, or if the payload has sensitive claims you cannot expose. Keep in mind that encryption adds complexity,encrypted tokens still need signature or integrity checks in many designs, and encrypted tokens are larger and cost more to process. For many systems, a combined approach of signing then encrypting (sign-then-encrypt) gives the strongest guarantees.
Summary
JWTs are a powerful tool for conveying identity and authorization, but they require careful handling. Sign tokens with strong algorithms, verify claims and signatures explicitly, avoid storing secrets in token payloads, protect tokens in transport and storage, and implement lifecycle controls such as short expirations, refresh token rotation, revocation mechanisms, and key rotation. With these controls in place, JWTs can provide efficient, secure stateless authentication that scales well across distributed systems.
FAQs
How should I store JWTs in a browser?
Prefer Secure, HttpOnly cookies with SameSite set and CSRF protection when the token is used for browser sessions. Storing tokens in localStorage exposes them to XSS attacks; if you must use client-side storage, invest heavily in XSS mitigation and consider short token lifetimes.
Is signing enough or do I need to encrypt JWTs?
Signing ensures integrity and authenticity but does not hide the payload. If the claims include sensitive personal data or travel through intermediate systems that must not read them, use JWE (encryption). For many authorization use cases, signed tokens with minimal claims are sufficient.
How do I revoke a JWT before it expires?
Use short-lived access tokens and revoke longer-lived refresh tokens server-side. Implement a revocation list keyed by token ID (jti) or keep a session table. Alternatively, use opaque tokens with an introspection endpoint so the authorization server can immediately reject revoked tokens.
Which signing algorithm should I use for production?
Prefer asymmetric algorithms like RS256 or ES256 for distributed systems where many services verify tokens but should not have the private key. If you use symmetric algorithms like HS256, ensure secrets are strong, rotated, and tightly controlled.
How should I handle key rotation securely?
Publish public keys via a JWKS endpoint with key IDs (kid). When rotating, add the new key while keeping the old key until all issued tokens signed by it have expired. Automate rotation and monitoring, and remove old keys only after a safe overlap period to avoid verification failures.
