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.

Practice

1. What is the main purpose of JWT token propagation in a microservices architecture?

easy

A. To encrypt all communication between microservices

B. To store user data permanently in each microservice

C. To securely share user identity information across multiple services

D. To replace API keys for service-to-service authentication

Solution

1. Step 1: Understand JWT token role

   JWT tokens carry user identity and claims securely in a compact form.

2. Step 2: Identify propagation purpose

   Propagating JWT tokens allows each microservice to verify and trust the user's identity without storing it locally.

3. Final Answer:

   To securely share user identity information across multiple services -> Option C

4. Quick Check:

   JWT propagation = share identity securely [OK]

Hint: JWT tokens carry user identity for trust across services [OK]

Common Mistakes:

• Confusing JWT propagation with data storage
• Thinking JWT encrypts all communication
• Assuming JWT replaces all authentication methods

2. Which HTTP header is commonly used to forward the JWT token between microservices?

easy

A. Authorization

B. X-Auth-Token

C. Cookie

D. Content-Type

Solution

1. Step 1: Identify standard header for tokens

   The Authorization header is the standard way to send bearer tokens like JWT in HTTP requests.

2. Step 2: Confirm other headers' roles

   X-Auth-Token is less standard, Cookie is for browser sessions, Content-Type defines data format.

3. Final Answer:

   Authorization -> Option A

4. Quick Check:

   JWT token sent in Authorization header [OK]

Hint: JWT tokens go in Authorization header as Bearer [OK]

Common Mistakes:

• Using Cookie header for token forwarding
• Confusing Content-Type with authentication headers
• Assuming custom headers like X-Auth-Token are standard

3. Consider this code snippet in a microservice forwarding a JWT token:

fetch('http://serviceB/api', {
  headers: { 'Authorization': req.headers['authorization'] }
})

What will happen if the original request has no Authorization header?

medium

A. The Authorization header is set to an empty string

B. Service B receives an Authorization header with value 'undefined'

C. The fetch call throws an error and fails

D. Service B receives the request without any Authorization header

Solution

1. Step 1: Check header forwarding code

   The code forwards req.headers['authorization'] directly as the Authorization header value.

2. Step 2: Understand missing header behavior

   If req.headers['authorization'] is undefined, the header is omitted in fetch, so Service B gets no Authorization header.

3. Final Answer:

   Service B receives the request without any Authorization header -> Option D

4. Quick Check:

   Missing header means no Authorization sent [OK]

Hint: Undefined header means no header sent, not 'undefined' string [OK]

Common Mistakes:

• Assuming 'undefined' string is sent as header value
• Expecting fetch to throw error on missing header
• Thinking header is set to empty string automatically

4. A microservice fails to verify JWT tokens from upstream services. Which of these is the most likely cause?

medium

A. The microservice does not forward the Authorization header

B. The microservice uses a different secret or public key to verify tokens

C. The microservice sends tokens in the request body instead of headers

D. The microservice caches tokens for too long

Solution

1. Step 1: Analyze verification failure causes

   Verification fails if the microservice uses a wrong secret or public key to check the JWT signature.

2. Step 2: Evaluate other options

   Not forwarding headers causes downstream issues, sending tokens in body is non-standard but not verification failure, caching affects freshness but not signature verification.

3. Final Answer:

   The microservice uses a different secret or public key to verify tokens -> Option B

4. Quick Check:

   Wrong key = verification fails [OK]

Hint: Verification needs matching secret/public key [OK]

Common Mistakes:

• Confusing forwarding issues with verification errors
• Assuming token location affects signature verification
• Ignoring key mismatch as cause of failure

5. In a microservices system, Service A receives a JWT token from a user and calls Service B, which calls Service C. To ensure secure JWT token propagation and verification, which design is best?

hard

A. Service A sends the JWT to Service B, which forwards the same JWT to Service C; each service verifies the token locally

B. Service A sends the JWT to Service B; Service B generates a new token for Service C with its own secret

C. Service A sends the JWT only to Service B; Service B calls Service C without any token

D. Service A sends the JWT to Service B; Service B stores the token and Service C fetches it from Service B when needed

Solution

1. Step 1: Understand token propagation best practice

   JWT tokens should be forwarded unchanged so each service can verify the original user identity and claims.

2. Step 2: Evaluate alternatives

   Generating new tokens breaks trust chain; skipping tokens breaks authentication; fetching tokens from another service adds complexity and risk.

3. Final Answer:

   Service A sends the JWT to Service B, which forwards the same JWT to Service C; each service verifies the token locally -> Option A

4. Quick Check:

   Forward original JWT for trust and verification [OK]

Hint: Forward original JWT unchanged for trust across services [OK]

Common Mistakes:

• Creating new tokens at intermediate services
• Not forwarding tokens to all downstream services
• Relying on token fetching instead of forwarding