JWT token propagation in Microservices - System Design Guide

Problem Statement

When a user makes a request to a microservices system, the initial authentication token must be trusted and passed along to downstream services. Without proper token propagation, downstream services cannot verify the user's identity or permissions, leading to security gaps or repeated authentication calls that increase latency and complexity.

Solution

JWT token propagation involves forwarding the original JWT token received from the client through each microservice call. Each service extracts the token from the request headers, validates it locally without needing to call the authentication server again, and uses the token claims to enforce authorization. This keeps the user context intact across service boundaries efficiently.

Architecture

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Client    │─────▶│  Service A  │─────▶│  Service B  │
│ (with JWT)  │      │ (validates  │      │ (validates  │
└─────────────┘      │  JWT token) │      │  JWT token) │
                     └─────────────┘      └─────────────┘

This diagram shows a client sending a request with a JWT token to Service A, which validates and forwards the same token to Service B for validation and authorization.

Trade-offs

✓ Pros

→

Reduces authentication server load by enabling local token validation in each service.

→

Maintains user identity and permissions consistently across microservices.

→

Improves performance by avoiding repeated authentication calls.

→

Simplifies authorization logic by using token claims directly.

✗ Cons

→

Requires all services to implement JWT validation logic correctly.

→

Token revocation is difficult since tokens are self-contained and stateless.

→

If token contains sensitive data, it must be securely signed and encrypted.

Use when microservices need to authenticate and authorize user requests independently at scale, especially when read traffic exceeds thousands of requests per second.

Avoid when tokens need frequent revocation or real-time permission changes, or when services cannot securely handle token validation.

Real World Examples

Netflix

Netflix propagates JWT tokens across its microservices to maintain user session context and permissions without central authentication calls, improving streaming performance.

Uber

Uber uses JWT token propagation to securely pass user identity and roles between services like ride matching and payment processing, ensuring consistent authorization.

Shopify

Shopify propagates JWT tokens in its microservices to allow independent services to validate user permissions for store management and order processing.

Code Example

The before code shows Service A calling Service B without forwarding the JWT token, so Service B cannot authenticate the user. The after code extracts the JWT token from the incoming request headers in Service A and forwards it to Service B. Service B then validates the token locally before processing the request, enabling secure token propagation.

Microservices

### Before: No token propagation, downstream service cannot authenticate

# Service A handler

def service_a_handler(request):
    # Process request without forwarding token
    response = call_service_b(request.data)
    return response


### After: Propagate JWT token in headers

# Service A handler

def service_a_handler(request):
    jwt_token = request.headers.get('Authorization')
    headers = {'Authorization': jwt_token} if jwt_token else {}
    response = call_service_b(request.data, headers=headers)
    return response

# Service B handler

def service_b_handler(request):
    jwt_token = request.headers.get('Authorization')
    if not validate_jwt(jwt_token):
        return {'error': 'Unauthorized'}, 401
    # Proceed with authorized request
    return {'data': 'success'}

# Helper function

def validate_jwt(token):
    # Simplified validation logic
    if token and token.startswith('Bearer '):
        # Decode and verify signature, expiry, etc.
        return True
    return False

Alternatives

OAuth 2.0 Token Introspection

Instead of propagating JWT tokens, each service calls a central authorization server to validate tokens on every request.

Use when: Choose when token revocation and real-time permission updates are critical and token validation must be centralized.

Session-based Authentication

User session state is stored centrally and services rely on session IDs instead of self-contained tokens.

Use when: Choose when maintaining server-side session state is acceptable and token statelessness is not required.

Summary

JWT token propagation forwards the user's authentication token across microservices to maintain identity and permissions.

Each service validates the token locally to avoid repeated calls to the authentication server.

This pattern improves performance and consistency but requires careful token management and validation.