Stage 9. JWT Basics
JWT (JSON Web Token) is a compact format for transferring claims between parties, most commonly between client applications and APIs. JWT is often described as “great for microservices,” but that is true only with strict validation architecture. A token alone is not security. Security comes from correct issuance, consistent validation, and disciplined key management.
1. What JWT Is and Why Teams Use It
JWT is used when APIs need stateless authorization checks without reading server-side session state on every request. After login, client receives an access token and sends it in the Authorization header.
Authorization: Bearer <access-token>
Main benefit: each API can validate token locally. Main tradeoff: immediate revocation is harder, so systems usually rely on short token TTL plus separate revocation controls.
2. JWT Parts and Meaning
A JWT has three dot-separated parts:
header.payload.signature
header: signing algorithm and token metadata.payload: claims such assub,iss,aud,exp, scopes, roles.signature: integrity and issuer authenticity check.
Important: payload is usually not encrypted by default. It is base64url-encoded and easy to decode, so sensitive data should not be placed there.
3. End-to-End JWT Flow in Microservices (one token -> multiple services)
Typical production flow:
- Client authenticates with Auth Server.
- Auth Server issues access JWT.
- Client calls API Gateway using bearer token.
- Gateway performs first-layer validation.
- Request reaches microservices, and each service validates token again.
- Services verify signatures using public keys/JWKS with key-rotation support.
Core rule: do not rely on gateway validation only. Every service that enforces authorization decisions must validate JWT independently.
4. Mandatory Validation Checks per API
| Check | Why it matters |
|---|---|
| Signature + algorithm allow-list | Prevents tampered tokens and unsafe alg usage |
iss (issuer) | Ensures token came from trusted auth server |
aud (audience) | Ensures token is intended for this API |
exp, nbf, iat | Enforces valid time window |
| Token type | Prevents ID-token vs access-token confusion |
| Scopes/Roles | Enforces domain permissions |
Validating only exp is never enough for a production API.
5. Microservice Operations Theory
Consistency is the priority. If one service validates aud and another ignores it, users see random 401/403 behavior with the same token. Teams should use shared policy libraries or a centrally managed validation contract.
Key rotation is equally critical. Services must accept new keys safely and support overlap windows, otherwise rotations can trigger large-scale auth failures.
6. Frequent Beginner Mistakes
- Putting sensitive personal or internal data into JWT payload.
- Checking only signature and
exp. - Accepting ID tokens as access tokens.
- Setting very long access-token TTL for convenience.
- Not logging validation failure reasons (
bad_signature,wrong_aud,token_expired).
Practical scenario
An organization had three microservices behind one gateway. Gateway validated signature and expiration, but one service required aud=payments while another did not validate aud at all. The same token worked in one flow and failed in another, creating unstable user experience. After adopting a shared validation policy (alg, iss, aud, time claims, token type, scopes), enabling JWKS-based key rotation, and standardizing validation-failure logs, the authorization flow became predictable. The lesson is practical: JWT is reliable only as a system-wide validation discipline, not as a standalone token format.