JWT token propagation in Microservices - System Design Exercise

Design: JWT Token Propagation in Microservices

Design focuses on token propagation and verification across microservices. User authentication service and token issuance are in scope. Token refresh and revocation mechanisms are included. Out of scope are UI design and detailed cryptographic algorithms.

Functional Requirements

FR1: Authenticate users once and propagate their identity securely across multiple microservices.

FR2: Each microservice must verify the JWT token to authorize requests.

FR3: Support token expiration and refresh mechanisms.

FR4: Ensure minimal latency added by token verification.

FR5: Allow token revocation or blacklisting for security.

FR6: Support scalability to handle 10,000 concurrent user requests.

Non-Functional Requirements

NFR1: API response latency p99 should be under 200ms including token verification.

NFR2: System availability target is 99.9% uptime.

NFR3: Tokens must be securely transmitted and stored to prevent leaks.

NFR4: Microservices communicate over REST or gRPC.

NFR5: No centralized session storage to maintain statelessness.

Think Before You Design

Questions to Ask

❓ Question 1

❓ Question 2

❓ Question 3

❓ Question 4

❓ Question 5

❓ Question 6

Key Components

Authentication Service (Token Issuer)

API Gateway or Edge Service

Microservices with token verification logic

Token Revocation Store or Blacklist

Token Refresh Service

Secure communication channels (HTTPS, mTLS)

Design Patterns

Stateless Authentication with JWT

Token Propagation via HTTP Headers

API Gateway Token Validation

Token Blacklisting for Revocation

Refresh Token Pattern

Distributed Tracing for request flow

Reference Architecture

  +-------------------+        +-------------------+        +-------------------+
  |                   |        |                   |        |                   |
  | Authentication    |        | API Gateway       |        | Microservice A    |
  | Service           |        | (Token Validator) |        | (Token Validator) |
  | (Token Issuer)    |        |                   |        |                   |
  +---------+---------+        +---------+---------+        +---------+---------+
            |                            |                            |
            | 1. Issue JWT Token         |                            |
            |--------------------------->|                            |
            |                            |                            |
            |                            | 2. Forward request with JWT|
            |                            |---------------------------->
            |                            |                            |
            |                            |                            | 3. Validate JWT Token
            |                            |                            |<---------------------------
            |                            |                            |
            |                            |                            | 4. Process request
            |                            |                            |--------------------------->
            |                            |                            |
            |                            |                            |
  +-------------------+        +-------------------+        +-------------------+
  |                   |        |                   |        |                   |
  | Token Revocation   |        | Microservice B    |        | Token Refresh     |
  | Store (Blacklist)  |        | (Token Validator) |        | Service           |
  |                   |        |                   |        |                   |
  +-------------------+        +-------------------+        +-------------------+

Components

Authentication Service

Node.js / Spring Boot / Python Flask

Issues JWT tokens after user login with claims and expiration.

API Gateway

Kong / NGINX / Envoy

Receives client requests, validates JWT tokens, and forwards requests to microservices.

Microservices

Any language/framework supporting JWT verification

Verify JWT tokens on each request to authorize user actions.

Token Revocation Store

Redis or in-memory cache

Stores blacklisted tokens or token IDs to reject revoked tokens.

Token Refresh Service

Part of Authentication Service or separate microservice

Handles refresh tokens to issue new JWT tokens when old ones expire.

Request Flow

1. User logs in to Authentication Service and receives a JWT token.

2. User sends requests to API Gateway with JWT token in Authorization header.

3. API Gateway validates the JWT token signature and expiration.

4. If valid, API Gateway forwards the request with the token to the target microservice.

5. Microservice verifies the JWT token claims and checks token revocation store.

6. If token is valid and not revoked, microservice processes the request and returns response.

7. If token is expired, client uses refresh token with Token Refresh Service to get a new JWT token.

8. Token Revocation Store is checked on each request to reject revoked tokens.

Database Schema

Entities: - User: id, username, password_hash, roles - JWT Token: token_id (jti), user_id, issued_at, expires_at, revoked (boolean) - Refresh Token: token_id, user_id, issued_at, expires_at, revoked Relationships: - User 1:N JWT Tokens - User 1:N Refresh Tokens Notes: - JWT tokens are stateless but token_id (jti) is stored for revocation checks. - Revoked tokens are marked or stored in a fast-access cache like Redis.

Scaling Discussion

Bottlenecks

API Gateway becoming a bottleneck due to token validation on every request.

Token Revocation Store latency impacting request processing.

High load on Authentication Service during token refresh bursts.

Network latency between microservices for token verification.

Storage growth for revoked tokens and refresh tokens.

Solutions

Use distributed API Gateway clusters with load balancing to handle high traffic.

Cache revocation data locally in microservices with short TTL to reduce remote calls.

Implement rate limiting and backoff on token refresh requests.

Use asynchronous token validation or offload some checks to API Gateway.

Periodically clean up expired revoked tokens and refresh tokens from storage.

Interview Tips

Time: Spend 10 minutes understanding requirements and clarifying assumptions, 20 minutes designing the architecture and data flow, 10 minutes discussing scaling and security considerations, and 5 minutes summarizing.

Explain stateless nature of JWT and benefits for microservices.

Discuss token verification at API Gateway vs microservices trade-offs.

Highlight importance of token revocation and refresh mechanisms.

Address security concerns like token leakage and secure transmission.

Show awareness of latency and scalability challenges and solutions.