Episode 18 · Module 5 · Authentication & Identity

JWT Anatomy and Pitfalls

18 May 2026 · 9:53 · Security for Legal SaaS

9:53 9:53

JSON Web Tokens transformed web authentication — and introduced a new class of vulnerabilities. Alice and Dan dissect the three-part JWT structure (header, payload, signature), the infamous “none” algorithm attack, algorithm confusion (RS256 to HS256), token lifetime tradeoffs, the access-plus-refresh pattern, what JWTs fundamentally cannot do (immediate revocation), and when server-side sessions are the better choice for legal SaaS handling privileged documents.

Today’s Lesson

Security for Legal SaaS — Episode 18: JWT Anatomy and Pitfalls

The Token That Changed Web Authentication

JSON Web Tokens transformed how web applications handle authentication. Instead of server-side session storage, a JWT encodes identity claims into a self-contained, cryptographically signed token that the client carries. RFC 7519 defines the standard — and since its publication in 2015, JWTs have become the default authentication mechanism for SPAs (Single-Page Applications — web apps where the entire interface runs in the browser), mobile apps, and API services.

Key insight: JWTs shift trust from server state to cryptographic verification. This is powerful — and dangerous. Every vulnerability in JWT implementation is a vulnerability in your entire authentication layer. PortSwigger’s JWT security research documents over a dozen exploitable attack patterns.

For legal SaaS, where multi-tenant isolation and privilege boundaries are existential concerns, understanding exactly what JWTs guarantee — and what they cannot — is the difference between secure architecture and a breach waiting for a trigger.

JWT Structure — Three Parts, Base64-Encoded

A JWT consists of three Base64URL-encoded segments separated by dots: header.payload.signature.

Header

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "2024-signing-key-01"
}

The header declares the signing algorithm and optionally a key ID for key rotation. RFC 7518 (JSON Web Algorithms) defines the allowed algorithms.

Payload (Claims)

{
  "sub": "user_8f3a2b",
  "iss": "https://auth.legalplatform.com",
  "aud": "https://api.legalplatform.com",
  "iat": 1716000000,
  "exp": 1716003600,
  "tenant_id": "firm_baker_mckenzie",
  "role": "partner",
  "scope": "documents:read documents:write matters:read"
}

Claim	Purpose	Security Implication
`sub`	Subject (user ID)	Must be opaque — never use email addresses
`iss`	Issuer	Verify on every request — reject tokens from unexpected issuers
`aud`	Audience	The service this token is intended for — reject mismatched audiences
`exp`	Expiration	Enforce strictly — no grace periods beyond clock skew
`iat`	Issued at	Enables detection of tokens issued before a security event
`tenant_id`	Custom: tenant isolation	Enforce at API layer — never trust the token alone for tenant boundaries
`scope`	Permissions	Principle of least privilege — request minimum needed

Signature

The signature is computed over the header and payload: HMAC-SHA256(base64url(header) + "." + base64url(payload), secret) for symmetric algorithms, or an RSA/ECDSA signature for asymmetric ones.

The “none” Algorithm Attack

Critical vulnerability: Auth0’s 2015 disclosure revealed that multiple JWT libraries accepted tokens with "alg": "none" — the “unsecured JWS” defined in RFC 7519. An attacker strips the signature entirely, sets the algorithm to “none,” modifies any claims they want (escalate role, change tenant_id), and the server accepts it.

How it works:

Attacker intercepts a valid JWT
Decodes the header, changes "alg": "RS256" to "alg": "none"
Modifies payload claims (elevate privileges, switch tenants)
Removes the signature segment
Sends: eyJ...modified_header.eyJ...modified_payload.

Defence: Never allow the token to specify its own algorithm. Configure your verification library with a hardcoded expected algorithm. Reject any token whose header algorithm doesn’t match. Most modern libraries do this by default, but legacy code and misconfiguration remain common.

Algorithm Confusion (RS256 → HS256)

A subtler variant: if a server uses RS256 (asymmetric — signs with private key, verifies with public key), an attacker can:

Obtain the public key (often exposed at /.well-known/jwks.json — JWKS being the JSON Web Key Set, a standard endpoint where servers publish their public signing keys)
Set the header algorithm to HS256 (symmetric)
Sign the modified token using the public key as the HMAC secret
If the server blindly trusts the algorithm header, it verifies using the public key as an HMAC secret — and the signature passes

Tim McLean’s original research demonstrated this across multiple JWT libraries. The fix: always specify the expected algorithm in your verification call.

Token Lifetime Tradeoffs

Parameter	Short-Lived (5–15 min)	Long-Lived (hours/days)
Exposure window	Minimal	Dangerous
User friction	Frequent re-auth (mitigated by refresh tokens)	Seamless
Revocation need	Low — tokens expire naturally	High — can’t wait for expiry
Storage risk	Lower impact if stolen	Catastrophic if stolen

Access + Refresh Token Pattern

OAuth 2.0 (RFC 6749) established the pattern:

Access token: Short-lived (5–15 minutes). Sent with every API request. Stateless verification.
Refresh token: Longer-lived (days–weeks). Stored securely. Exchanged for new access tokens. Can be revoked server-side.

For legal SaaS: access token at 15 minutes (short enough that revocation is rarely needed), refresh token at 7 days (stored in httpOnly cookie, rotated on each use). OWASP recommends refresh token rotation — if a refresh token is used twice (indicating theft), invalidate all tokens for that user immediately.

What JWTs Cannot Do

Immediate Revocation

JWTs are verified without contacting the server. Once issued, they’re valid until expiry. You cannot “delete” a JWT. This creates a fundamental problem: if a user’s account is compromised, if they’re deprovisioned, if their permissions change — the existing JWT remains valid until it naturally expires.

Strategy	Latency	Cost
Short expiry (5 min)	5 min max exposure	Frequent refreshes
Token blocklist (Redis/memory)	Near-instant	Requires server state — partially defeats the purpose
Token versioning (per-user counter)	On next verification	Requires database lookup — partially defeats the purpose
Event-driven invalidation	Seconds (pub/sub)	Infrastructure complexity

Server-Side State

The promise of JWTs is statelessness. But real applications need revocation, audit logging, concurrent session limits, and permission changes to take effect immediately. Thomas Ptacek’s critique: “If you need server-side state anyway (and you do), you might as well use sessions.”

Pragmatic guidance: Use JWTs for stateless service-to-service authentication where revocation is less critical. Use stateful sessions (server-side session ID in a cookie) for user-facing authentication where you need immediate revocation, concurrent session control, and activity tracking. Many production systems use both — JWT between microservices (small, independent services that each handle one function), sessions for the user-facing layer.

When to Use JWTs vs Stateful Sessions

Criterion	JWT	Stateful Session
Immediate revocation needed	No — use sessions	Yes
Distributed microservices	Yes — no shared session store needed	Requires distributed cache
Concurrent session limits	Difficult	Native
Audit trail of active sessions	Difficult	Native
Scalability	Excellent — no server state	Requires session store scaling
Offline/mobile	Good — token is self-contained	Requires connectivity
Sensitive legal operations	Consider sessions	Preferred

OWASP’s Session Management Cheat Sheet recommends server-side sessions for applications requiring “immediate invalidation capability” — which describes every legal SaaS platform handling privileged documents.

JWT Security Checklist for Legal SaaS

Control	Implementation
Algorithm hardcoding	Verify with explicit `algorithms=["RS256"]` — never trust the header
Signature verification	Verify every token on every request — no exceptions
Claims validation	Check `iss`, `aud`, `exp`, `iat` on every verification
Key management	Rotate signing keys annually; support multiple `kid` values during rotation
Token storage (browser)	httpOnly, Secure, SameSite=Strict cookies — never localStorage
Refresh token rotation	New refresh token on each use; detect reuse as compromise
Scope minimisation	Issue tokens with minimum required permissions
Tenant isolation	Validate `tenant_id` claim against the resource being accessed — defence in depth
Clock skew	Maximum 30 seconds tolerance for `exp` verification
Token size	Keep payloads minimal — JWTs travel with every request

The jwt.io debugger is invaluable for inspecting tokens during development — but note that pasting production tokens into third-party websites exposes their contents. Decode locally with base64 -d for production tokens.

Real-World JWT Vulnerabilities

In 2022, researchers discovered that Microsoft Azure AD tokens could be forged due to a validation bypass — the Storm-0558 incident where a stolen signing key allowed forging tokens for any Azure AD user. The Auth0 “algorithm confusion” disclosure affected libraries in Java, Node.js, PHP, and Python simultaneously.

For legal SaaS, a forged JWT with an elevated tenant_id or role claim means an attacker can access another firm’s privileged documents. The cryptographic signature is the only barrier — and it’s only as strong as your algorithm choice, key management, and verification implementation.

RFC 9068 (JWT Profile for OAuth 2.0 Access Tokens) standardises the claims structure for access tokens, providing interoperability guidelines that reduce implementation errors.

Conclusion

JWTs are powerful but unforgiving. The “none” algorithm attack, algorithm confusion, and the fundamental inability to revoke issued tokens make JWT security a matter of precise implementation, not conceptual understanding. Hardcode your algorithms. Validate every claim. Keep access tokens short-lived. Use refresh token rotation. And ask the honest question: does your application actually need stateless tokens, or would server-side sessions — simpler, revocable, auditable — serve your security requirements better?

For legal SaaS handling privileged communications across multi-tenant boundaries, the answer is often both: sessions for user-facing authentication, JWTs for internal service communication.

Next episode: Session Management — the server-side approach, done right: from ID generation through lifecycle to invalidation.

Alice: Welcome back to Security for Legal SaaS. I’m Alice.

Dan: And I’m Dan. Episode 18 — JWT Anatomy and Pitfalls. Alice, JSON Web Tokens are everywhere. Every tutorial, every framework, every “build an auth system in 10 minutes” blog post uses them. What’s the actual security story?

Alice: JWTs solved a real problem — how do you authenticate requests across distributed services without every service needing to query a central session store? The answer is a self-contained token. You encode the user’s identity and permissions into a JSON payload, sign it cryptographically, and the client carries it with every request. Any service can verify the signature locally without network calls.

Dan: Break down the structure for me.

Alice: Three parts separated by dots. The header — which declares the signing algorithm and optionally a key ID. The payload — which contains claims about the user: who they are, when the token expires, what they’re authorised to do. And the signature — which proves the header and payload haven’t been tampered with. All three parts are Base64URL-encoded — converted into a compact text format using letters, numbers, and a few symbols so they’re URL-safe strings you can put in HTTP headers.

Dan: And the signature is what gives you the security guarantee.

Alice: If it’s verified correctly, yes. The server computes the expected signature for the header and payload using its secret key, then compares it to the signature in the token. If they match, the claims are trustworthy — nobody modified them after signing. If they don’t match, the token is rejected. The entire security model rests on correct signature verification.

Dan: Which brings us to the infamous “none” algorithm attack.

Alice: In 2015, Auth0 disclosed that multiple JWT libraries — in Java, Node.js, PHP, and Python — accepted tokens with the algorithm set to “none.” That’s a special value defined in the RFC — the Request for Comments document that formally specifies the standard — meaning “this token is unsigned.” An attacker takes a valid token, decodes the header, changes the algorithm from RS256 — RSA with SHA-256 signing — to none, modifies any claims they want — elevate their role to admin, change their tenant ID to access another firm’s data — removes the signature entirely, and submits it. If the server trusts the algorithm specified in the token header, it sees “none,” skips verification, and accepts the forged token.

Dan: That’s catastrophic. How does it happen?

Alice: Because many libraries implemented verification like this: read the algorithm from the token header, then use that algorithm to verify. If the algorithm is “none,” verification trivially succeeds. The fix is simple — never let the token tell you how to verify it. Hardcode the expected algorithm in your verification call. If you expect RS256, pass algorithms equals RS256 explicitly. Reject anything else. Most modern libraries do this by default now, but legacy code and misconfigurations still exist.

Dan: There’s a more subtle variant too — algorithm confusion?

Alice: Yes. Say your server uses RS256 — asymmetric cryptography. It signs with a private key and verifies with a public key. The public key is often published at a well-known endpoint. An attacker obtains the public key, sets the algorithm header to HS256 — HMAC with SHA-256, which is symmetric cryptography — and signs the modified token using the public key as the HMAC secret. If the server reads the algorithm from the header and uses it, it performs HMAC verification with the public key — which is the same key the attacker used to sign. Verification passes. The forged token is accepted.

Dan: Same fix — hardcode the algorithm, never trust the header.

Alice: Exactly. The header is attacker-controlled input. Treat it accordingly.

Dan: Let’s talk about token lifetime. Short-lived versus long-lived — what’s the tradeoff?

Alice: Here’s the fundamental problem with JWTs — once issued, they’re valid until they expire. You cannot “delete” a JWT. You can’t revoke it without maintaining server-side state, which defeats the stateless purpose. So token lifetime is really a question of how long you’re willing to let a compromised token remain usable. A 15-minute access token means even if stolen, the window of exploitation is small. A 24-hour token means an attacker has a full day.

Dan: But 15-minute tokens mean the user keeps getting logged out.

Alice: That’s where refresh tokens come in. The OAuth 2.0 pattern — OAuth being the standard protocol for delegating access, which we’ll cover in depth in Episode 20 — uses two tokens. A short-lived access token — 5 to 15 minutes — sent with every API request. And a longer-lived refresh token — days or weeks — stored securely, used only to obtain new access tokens. The refresh token can be revoked server-side because it’s checked against a database on each use. You get the UX of persistent sessions with the security of short-lived credentials.

Dan: That makes sense. And refresh token rotation?

Alice: Critical. Every time a refresh token is used to obtain a new access token, you issue a new refresh token simultaneously and invalidate the old one. If an attacker steals a refresh token and the legitimate user also tries to use it, one of them will present an already-invalidated token. That’s your detection signal — immediately invalidate all tokens for that user and force re-authentication. OWASP recommends this pattern explicitly.

Dan: Now here’s the honest question — when should you not use JWTs?

Alice: When you need immediate revocation. When you need concurrent session limits — “only one active session per user.” When you need a real-time audit trail of active sessions. When a user changes their password and you want all other sessions to die instantly. JWTs can’t do any of these without adding server-side state. And if you’re adding server-side state anyway, you might as well use server-side sessions. Thomas Ptacek made this point years ago and it’s still valid.

Dan: So for legal SaaS — where you might need to immediately revoke access when a lawyer leaves a firm, or when privilege boundaries change mid-matter...

Alice: Stateful sessions are often the better choice for user-facing authentication. You get immediate revocation, activity tracking, concurrent session control, and a clear audit trail. The session ID is a random opaque token stored in an httpOnly cookie — it carries no claims, reveals nothing if intercepted, and can be invalidated in milliseconds by deleting the server-side record.

Dan: But JWTs still have their place?

Alice: Absolutely. Service-to-service communication within your infrastructure — where you control both sides and revocation is less critical. Microservice architectures — where your application is split into many small, independent services instead of one big program — where a gateway validates the user’s session and then issues a short-lived JWT for downstream services to consume without each needing session store access. That’s the sweet spot. The pattern many production systems use is sessions for the user-facing edge, JWTs for internal service communication.

Dan: What about storing JWTs in the browser?

Alice: Never in localStorage — that’s a storage area built into the browser that any JavaScript code on the page can read and write. It’s accessible to any JavaScript on the page — a single XSS vulnerability and the attacker exfiltrates the token. Store access tokens in memory — JavaScript variables that don’t survive page refresh. Store refresh tokens in httpOnly, Secure, SameSite=Strict cookies — inaccessible to JavaScript, only sent by the browser automatically. This gives you protection against both XSS and CSRF.

Dan: Quick summary of the non-negotiables for anyone implementing JWTs today?

Alice: Hardcode the expected algorithm — never trust the token header. Validate issuer, audience, and expiry on every request. Keep access tokens to 15 minutes maximum. Use refresh token rotation with reuse detection. Store tokens in httpOnly cookies, never localStorage. Rotate signing keys annually with overlapping key IDs. And ask yourself honestly whether you actually need JWTs or whether server-side sessions would serve your security requirements better with less implementation complexity.

Dan: Next episode — Session Management. The server-side approach we just advocated for — how to do it right, from ID generation through lifecycle to invalidation.

Alice: Until then, I’m Alice.

Dan: And I’m Dan.

Security for Legal SaaS is a series written with AI assistance. Alice and Dan are AI-generated voices — no professional advice here, just education.