JWT (JSON Web Tokens)¶
What it is¶
A JWT (RFC 7519) is a self-contained, cryptographically signed token. Unlike an opaque API key, the token itself carries the claims — user ID, roles, expiry — so the server can verify it without a database lookup. Verification is pure cryptography: check the signature, read the claims.
sequenceDiagram
participant C as Client
participant A as Auth Server
participant R as Resource Server
C->>A: POST /login (credentials)
A->>A: Sign JWT with private key/secret
A-->>C: eyJhbGciOi... (access token)
C->>R: GET /api/data<br>Authorization: Bearer eyJhbGciOi...
Note over R: Verify signature locally —<br>NO lookup needed
R-->>C: 200 OK
Anatomy of a JWT¶
Three Base64URL-encoded segments separated by dots:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
.
eyJzdWIiOiJhbGljZSIsImlzcyI6Imh0dHBzOi8vYXV0aC5leGFtcGxlLmNvbSIsImV4cCI6MTczMTk1ODQwMH0
.
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk...
| Segment | Decoded | Purpose |
|---|---|---|
| Header | {"alg":"RS256","typ":"JWT"} |
Signing algorithm and token type |
| Payload | {"sub":"alice","iss":"...","exp":...} |
The claims — who, issued by, expiry |
| Signature | raw bytes | Signature over header.payload |
Editable source: docs/diagrams/jwt-anatomy.drawio
The payload is readable by anyone
Base64URL is encoding, not encryption. Never put passwords, PII you wouldn't want disclosed, or secret data in a JWT. Signature guarantees integrity (can't be tampered), not confidentiality. For encrypted tokens look at JWE — a different spec.
Registered claims¶
Standardized in RFC 7519 — validate these on every request:
| Claim | Meaning | Validation rule |
|---|---|---|
iss |
Issuer | Must equal your expected issuer |
sub |
Subject (user ID) | Present and well-formed |
aud |
Audience | Must include your API's identifier |
exp |
Expiration time | Must be in the future |
iat |
Issued at | Sanity-check it's not in the future |
nbf |
Not before | If present, must be in the past |
jti |
Unique token ID | Use for revocation/dedup tracking |
Signing algorithms¶
| Alg | Type | When to use |
|---|---|---|
HS256 |
Symmetric HMAC | Single service that both issues and verifies tokens |
RS256 |
RSA asymmetric | Distributed systems — many verifiers, one issuer (public key shared via JWKS) |
EdDSA |
Ed25519 asymmetric | Modern choice — fast, small keys, no padding pitfalls |
Asymmetric beats symmetric at scale
With RS256/EdDSA, resource servers hold only the public key —
they can verify but never mint tokens. With HS256, every service that
can verify can also forge tokens.
Reference implementation¶
import datetime
import jwt
from jwt import PyJWKClient # fetches + caches JWKS
# ---- Issuing (auth server) ----
now = datetime.datetime.now(datetime.timezone.utc)
token = jwt.encode(
{
"sub": "alice",
"iss": "https://auth.example.com",
"aud": "orders-api",
"iat": now,
"exp": now + datetime.timedelta(minutes=15),
},
private_key_pem, # RSA private key — never on clients
algorithm="RS256",
)
# ---- Verifying (resource server) ----
jwks = PyJWKClient("https://auth.example.com/.well-known/jwks.json")
signing_key = jwks.get_signing_key_from_jwt(token)
try:
claims = jwt.decode(
token,
signing_key.key,
algorithms=["RS256"], # (1) pin the algorithm!
audience="orders-api", # (2)
issuer="https://auth.example.com",
)
except jwt.PyJWTError:
raise HTTPException(401, "Invalid token")
- Allowlisting
algorithmsprevents algorithm-confusion attacks. audandisschecks stop tokens minted for other services being replayed against yours.
// application.yml — that's all the wiring needed
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: https://auth.example.com
audiences: orders-api
@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http.authorizeHttpRequests(auth -> auth
.requestMatchers("/public/**").permitAll()
.anyRequest().authenticated())
.oauth2ResourceServer(oauth -> oauth
.jwt(Customizer.withDefaults()));
return http.build();
}
// Spring automatically: fetches JWKS from the issuer, verifies the
// signature, validates exp/iss/aud, and exposes claims via @AuthenticationPrincipal Jwt
Critical vulnerabilities¶
JWT's failure modes are mostly implementation bugs, not spec flaws. These are the ones that show up in real breaches:
1. Algorithm confusion (alg=none and RS256→HS256)¶
The alg header is attacker-controlled input. Two classic exploits:
alg: none— early libraries accepted unsigned tokens if the header saidnone. Modern libraries reject it; keep them patched.- RS256→HS256 confusion — if the server expects
RS256but a library acceptsHS256, the attacker signs a forged token with HMAC using the public key (which is public!) as the HMAC secret. The verifier happily validates it.
Mitigation: allowlist algorithms=["RS256"] server-side. Never trust
the header's alg value to choose the verification method.
2. Weak HMAC secrets¶
HS256 tokens are only as strong as the secret. Secrets like secret,
changeme, or short strings are brute-forced offline in seconds with tools
like hashcat (the attacker has the full token — verification is offline).
Mitigation: ≥256-bit random secrets from a secrets manager, or better — move to asymmetric algorithms.
3. Missing claim validation¶
Verifying the signature but ignoring exp, aud, or iss means:
expired tokens keep working, and tokens minted for a different service
(a weaker one) get replayed against yours.
Mitigation: validate exp, aud, iss every time — most libraries do
it only if you ask.
4. The revocation problem¶
Statelessness cuts both ways: a stolen JWT is valid until exp — the
server can't "delete" it without keeping state.
Mitigations, in order of pragmatism:
- Short
exp(5–15 min) + refresh tokens — limits blast radius - Blacklist
jtiin Redis for high-risk operations - Token version /
iatfloor — bump a per-usermin_iaton password change or incident response
5. Sensitive data in the payload¶
Anything in the payload is world-readable. Teams accidentally ship tokens with emails, internal IDs, or (yes) password hashes inside.
6. Key management failures¶
Hardcoded keys in source, no rotation, JWKS endpoints fetched over HTTP.
Mitigation: keys in a secrets manager/KMS, publish via JWKS, rotate on
a schedule, kid header for key selection.
Refresh tokens¶
Access tokens are short-lived by design; refresh tokens (long-lived, opaque, single-use) are exchanged at the auth server for new access tokens. Store refresh tokens hashed, rotate them on every use, and treat reuse of an old refresh token as a theft signal (invalidate the whole family).
Strengths & weaknesses¶
| Strengths | Weaknesses |
|---|---|
| Stateless verification — scales horizontally | Can't revoke without reintroducing state |
| Claims travel with the token — no lookup | Larger than opaque tokens (~1KB+ in headers) |
| Standardized — mature libraries in every language | Easy to misconfigure (the vulns above) |
| Asymmetric signing enables clean multi-service trust | Payload leaks data if you're careless |
| Works well for SPAs, mobile, microservices | Complexity: JWKS, rotation, refresh flows |
When to use / avoid¶
Use it for
- Microservice meshes where per-request DB lookups are too costly
- SPAs and mobile apps (usually issued via OAuth 2.0 / OIDC)
- Short-lived cross-service identity propagation
Avoid it for
- Long-lived tokens (the revocation problem bites hard)
- Carrying sensitive data
- Simple single-service APIs where a plain bearer token is enough — don't adopt JWT just because it's fashionable
Checklist¶
-
algorithmsallowlisted server-side —algheader never trusted -
exp≤ 15 min on access tokens;aud,iss,expvalidated - Asymmetric alg (RS256/EdDSA) when more than one service verifies
- No secrets or PII in the payload
- Keys in KMS/secrets manager; published via JWKS; rotated regularly
- Refresh tokens: hashed storage, rotation on use, reuse detection
- JWT libraries kept patched (the
alg=noneera lives in old versions)