Video summary

JWT Tokens in System Design: Full Tutorial with Refresh Tokens & Security

Main summary

Key takeaways

Technology

Key technological concepts & product/system design takeaways

Authentication vs. Authorization

  • Authentication answers who you are (login/identity verification).
  • Authorization answers what you can do (permissions/roles).
  • The tutorial focuses mainly on authentication because JWT is used to authenticate requests, and it also explains why JWT isn’t a sufficient sole source of authorization.

Problem with stateful, session-based auth

In stateful authentication, the server maintains session state (e.g., session ID mapped to user ID/role/expiry).

In microservices / horizontally scaled systems, session state is hard because:

  • Requests may hit different servers that don’t share the same session cache.
  • You may need a distributed session store (centralized cache/database), which reduces scalability.

Why JWT is introduced

JWT enables stateless authentication:

  • Microservices can validate the user without calling a centralized DB/cache.
  • The core requirement: each token must be self-sufficient for verification.

JWT structure (self-sufficient token)

JWT consists of three dot-separated parts:

  1. Header
    • Includes token type and algorithm.
  2. Payload
    • Includes user identity info, token metadata (e.g., issued-at/expiry), and may include roles.
  3. Signature
    • Provides integrity/tamper detection using cryptography.

Notes:

  • JWT components are Base64 encoded, but the security comes from the signature, not from encryption.

Security model: signature vs. decoding

  • Header and payload are not encrypted (only encoded), so anyone can decode them.
  • Therefore:
    • Do not put sensitive data (e.g., passwords) in the JWT payload.
    • Keep the payload minimal (avoid bloating tokens since they’re sent on every request).

Integrity protection flow

  • Token signing is performed at the authentication service using the private key.
  • Other microservices validate using the public key.
  • If a man-in-the-middle modifies the payload/header, the signature won’t verify, and the request is rejected.

Keys distribution via JWKS

  • Microservices and gateways fetch public keys from a JWKS (JSON Web Key Set) endpoint.
  • Services cache the JWKS periodically.
  • Keys are expected to be rotated, and services should verify using the current keys.

Gateway responsibilities (as described)

  • The API gateway performs JWT-based authentication.
  • Also mentioned:
    • Rate limiting
    • Routing/redirecting requests to the correct microservice

Refresh token tutorial content (practical flow + security reasoning)

Access token + refresh token

  • Short-lived access token (JWT)
    • Example: ~15 minutes
    • Limits damage if stolen.
  • Long-lived refresh token
    • Example: days/months
    • Reduces the need for users to re-login.

Refresh token rotation idea

  • When the access JWT expires, the client calls a refresh endpoint with the refresh token to obtain a new JWT.
  • Optionally rotate refresh tokens for improved security.

Logout behavior

  • The logout endpoint invalidates the refresh token server-side so it can’t be reused.

Extra mitigation mentioned

  • Bind refresh token usage to a device ID / IP fingerprint (or similar) to reduce misuse if stolen.

HTTP/storage guidance for clients

Web clients

  • Store JWT in HTTP-only cookies
    • Mentioned as better than local storage due to XSS risks.

Mobile/app clients

  • Store tokens in Keychain/Keystore.

API endpoints covered in the tutorial

POST /login

  • Returns:
    • JWT access token (header.payload.signature)
    • Refresh token
  • JWT includes expiry.
  • Context mentions HTTP-only for JWT.

Protected profile/service APIs (GET/POST)

  • Client sends JWT in request headers.
  • Services validate:
    • signature
    • expiry

POST /refresh

  • Client sends refresh token.
  • Server issues a new JWT.

POST /logout

  • Server invalidates refresh token(s) so they can’t mint new JWTs.

Review/analysis: “why not trust JWT for authorization”

Even if a JWT payload contains roles, the tutorial explains why authorization shouldn’t rely blindly on JWT claims:

  • If a user’s role changes in the backend while an old JWT is still valid (e.g., role downgraded), that existing JWT may still grant permissions until it expires.

Therefore:

  • Authorization decisions should be validated against a server-side source (DB/cache), not trusted JWT role claims alone.

Refresh token types & storage policy

Is refresh token also a JWT?

Refresh tokens can be:

  • Opaque refresh tokens (most common)
    • Stored in DB (often store only a hash)
    • Supports revocation/rotation/invalidation
  • JWT refresh tokens
    • Structured like JWT (more stateless)
    • Tradeoffs include harder immediate revocation

Where the backend stores tokens

  • JWT access token
    • Generally not stored server-side (stateless).
  • Refresh token
    • If opaque: typically stored hashed in DB to support revocation/logout/blocking stolen tokens.
    • If JWT refresh token: may be treated statelessly (less revocation control).

Main speaker/source

  • Mohit Sabda (sign-off: “Mohit Sabda signing off”)

Original video