Token Propagation Strategies

In modern distributed systems and microservices architectures, a key challenge is propagating user identity and authorization across services. After a user authenticates at the API Gateway, downstream services—like Order, Inventory, or Payment—need to know the user’s identity and permissions.

Token propagation ensures secure transfer of authentication tokens across services, maintaining user identity without repeatedly calling the Identity Provider (IdP).

What Is Token Propagation?

Token propagation is the process of forwarding authentication tokens (e.g., JWTs or OAuth2 access tokens) from one service to another across service chains.

Benefits:

• Preserves user identity across microservices
• Eliminates repeated calls to the IdP
• Keeps services stateless
• Maintains secure and authorized requests

Common Token Propagation Strategies

1. JWT (JSON Web Token) Relay

• The API Gateway validates the JWT and forwards it downstream
• Each downstream service verifies the token and enforces authorization rules
• Enables stateless, scalable communication

Example Flow:

Client → API Gateway → Order Service → Inventory Service → Payment Service

Spring Boot Practical Example:

Gateway Configuration (application.yml):

spring:
  cloud:
    gateway:
      routes:
        - id: order-service
          uri: lb://order-service
          predicates:
            - Path=/orders/**
          filters:
            - TokenRelay=

Order Service Security Config:

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/orders/**").hasAuthority("SCOPE_read")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2.jwt());
        return http.build();
    }
}

Simple, efficient, stateless, identity travels with requests

2. Token Exchange Pattern

• Service A requests a new token scoped for Service B from the IdP instead of forwarding the original token
• Service B validates the new token independently
• Provides fine-grained control and better isolation

Example Flow:

Client → API Gateway → ServiceA → IdP (Token Exchange) → ServiceB

Spring Boot Practical Example:

OAuth2AuthorizedClient authorizedClient = authorizedClientService
    .loadAuthorizedClient("client-id", "principalName");

OAuth2AccessToken newToken = tokenExchangeService.exchangeToken(
    authorizedClient.getAccessToken(), "service-b-scope");

WebClient webClient = WebClient.builder()
    .defaultHeader(HttpHeaders.AUTHORIZATION, "Bearer " + newToken.getTokenValue())
    .build();

Ensures downstream services only get limited, scoped access; ideal for sensitive or multi-tenant systems

3. OAuth2 Client Credentials Flow (Service-to-Service Tokens)

• Services authenticate to each other using client credentials (no user context)
• The downstream service validates the token to allow access

Spring Boot Example:

@Bean
WebClient webClient(ReactiveClientRegistrationRepository clientRegistrations,
                    ServerOAuth2AuthorizedClientRepository authorizedClients) {
    ServletOAuth2AuthorizedClientExchangeFilterFunction oauth2 =
        new ServletOAuth2AuthorizedClientExchangeFilterFunction(clientRegistrations, authorizedClients);
    oauth2.setDefaultClientRegistrationId("service-b-client");
    
    return WebClient.builder()
        .apply(oauth2.oauth2Configuration())
        .build();
}

Background jobs or service-to-service communication without user context

4. Legacy Session-Based Propagation (Not Recommended)

• Uses centralized session storage (Redis, database) to share user identity
• Services query the session store to authenticate requests
• Drawbacks: Not stateless, high latency, poor scalability for cloud-native systems

Best Practices for Token Propagation

• Validate tokens at every service (signature, expiration, audience, scopes)
• Use short-lived tokens and combine with refresh tokens
• Use mTLS for all internal service-to-service calls
• Avoid sensitive data in tokens (JWT payload is encoded, not encrypted)
• Consider token rotation strategies
• Log token usage for auditing and troubleshooting

Real-World Use Cases

Conclusion

Token propagation is essential in distributed systems to maintain identity, enforce authorization, and ensure secure communication across services.

• JWT Relay: Best for simple, stateless propagation across microservices
• Token Exchange: Best for fine-grained security, scoped access, and sensitive systems
• Client Credentials Flow: Best for service-to-service authentication without user identity