Spring Cloud Gateway in Production: Routing, Rate Limiting, JWT Auth & Resilience (2026)

spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: http://192.168.1.10:8081    # Hardcoded IP — breaks on any deployment
          predicates:
            - Path=/api/users/**

spring:
  cloud:
    gateway:
      discovery:
        locator:
          enabled: true
          lower-case-service-id: true
      routes:
        - id: user-service
          uri: lb://user-service          # lb:// uses Eureka/Consul + Ribbon/LoadBalancer
          predicates:
            - Path=/api/v1/users/**
          filters:
            - StripPrefix=2               # /api/v1/users/1 -> /users/1
            - AddRequestHeader=X-Gateway-Version, 2.0
            - name: CircuitBreaker
              args:
                name: user-service-cb
                fallbackUri: forward:/fallback/user-service
            - name: RequestRateLimiter
              args:
                redis-rate-limiter.replenishRate: 100
                redis-rate-limiter.burstCapacity: 200
                key-resolver: "#{@userIdKeyResolver}"

@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 1)
public class CorrelationIdGlobalFilter implements GlobalFilter {
    private static final String CORRELATION_HEADER = "X-Correlation-Id";

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String correlationId = exchange.getRequest().getHeaders()
            .getFirst(CORRELATION_HEADER);
        if (correlationId == null) {
            correlationId = UUID.randomUUID().toString();
        }
        final String finalId = correlationId;
        ServerHttpRequest mutatedRequest = exchange.getRequest().mutate()
            .header(CORRELATION_HEADER, finalId)
            .build();
        return chain.filter(exchange.mutate().request(mutatedRequest).build())
            .then(Mono.fromRunnable(() -> {
                exchange.getResponse().getHeaders().add(CORRELATION_HEADER, finalId);
            }));
    }
}

@Configuration
public class GatewayConfig {

    // Rate limit by authenticated user ID (from JWT claim)
    @Bean
    public KeyResolver userIdKeyResolver() {
        return exchange -> {
            String auth = exchange.getRequest().getHeaders().getFirst("Authorization");
            if (auth != null && auth.startsWith("Bearer ")) {
                try {
                    String token = auth.substring(7);
                    Jwt jwt = jwtDecoder.decode(token);
                    return Mono.just(jwt.getSubject());  // user ID from JWT
                } catch (Exception e) {
                    return Mono.just("anonymous-" + exchange.getRequest().getRemoteAddress()
                        .getAddress().getHostAddress());
                }
            }
            // Fallback: rate limit by IP for unauthenticated requests
            return Mono.just(exchange.getRequest().getRemoteAddress()
                .getAddress().getHostAddress());
        };
    }

    @Bean
    public RedisRateLimiter redisRateLimiter() {
        return new RedisRateLimiter(100, 200, 1);  // replenish=100/s, burst=200, tokens per request=1
    }
}

# application.yml Redis for rate limiting
spring:
  data:
    redis:
      host: redis-cluster.internal
      port: 6379
      lettuce:
        pool:
          max-active: 20
          min-idle: 5

@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class JwtAuthenticationFilter implements GlobalFilter {
    @Autowired private ReactiveJwtDecoder jwtDecoder;

    private static final Set<String> PUBLIC_PATHS = Set.of(
        "/api/v1/auth/login", "/api/v1/auth/register",
        "/actuator/health", "/actuator/info"
    );

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        String path = exchange.getRequest().getPath().value();
        if (PUBLIC_PATHS.stream().anyMatch(path::startsWith)) {
            return chain.filter(exchange);  // skip auth for public paths
        }

        String authHeader = exchange.getRequest().getHeaders().getFirst("Authorization");
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
            return exchange.getResponse().setComplete();
        }

        return jwtDecoder.decode(authHeader.substring(7))
            .flatMap(jwt -> {
                // Forward validated claims as trusted headers to downstream services
                ServerHttpRequest mutated = exchange.getRequest().mutate()
                    .header("X-User-Id", jwt.getSubject())
                    .header("X-User-Roles", String.join(",", jwt.getClaimAsStringList("roles")))
                    .header("X-User-Email", jwt.getClaimAsString("email"))
                    .build();
                return chain.filter(exchange.mutate().request(mutated).build());
            })
            .onErrorResume(e -> {
                exchange.getResponse().setStatusCode(HttpStatus.UNAUTHORIZED);
                return exchange.getResponse().setComplete();
            });
    }
}

resilience4j:
  circuitbreaker:
    instances:
      user-service-cb:
        sliding-window-type: COUNT_BASED
        sliding-window-size: 10
        failure-rate-threshold: 50        # open CB when 50% of last 10 calls fail
        wait-duration-in-open-state: 30s  # try again after 30s
        permitted-number-of-calls-in-half-open-state: 3
        record-exceptions:
          - java.net.ConnectException
          - java.util.concurrent.TimeoutException
  timelimiter:
    instances:
      user-service-cb:
        timeout-duration: 3s              # request timeout before CB counts it as failure

// FallbackController — meaningful degraded response
@RestController
public class FallbackController {
    @RequestMapping("/fallback/user-service")
    public ResponseEntity<Map<String, Object>> userServiceFallback() {
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
            .body(Map.of(
                "error", "User service is temporarily unavailable",
                "code", "SERVICE_UNAVAILABLE",
                "retryAfter", 30
            ));
    }
}

@Configuration
public class SecurityConfig {

    @Bean
    public CorsWebFilter corsWebFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.setAllowedOriginPatterns(List.of("https://*.myapp.com", "https://myapp.com"));
        config.setAllowedMethods(List.of("GET","POST","PUT","DELETE","OPTIONS","PATCH"));
        config.setAllowedHeaders(List.of("*"));
        config.setAllowCredentials(true);
        config.setMaxAge(3600L);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);
        return new CorsWebFilter(source);
    }

    @Bean
    public SecurityWebFilterChain securityFilterChain(ServerHttpSecurity http) {
        return http
            .headers(h -> h
                .frameOptions(ServerHttpSecurity.HeaderSpec.FrameOptionsSpec::deny)
                .contentTypeOptions(Customizer.withDefaults())
                .hsts(hsts -> hsts.maxAgeInSeconds(31536000).includeSubdomains(true))
                .xssProtection(Customizer.withDefaults()))
            .csrf(ServerHttpSecurity.CsrfSpec::disable)  // JWT is CSRF-safe
            .build();
    }
}

• JWT validation centralized at gateway
• Redis rate limiting per user/IP
• Circuit breaker on all downstream routes
• Correlation ID filter for tracing
• Centralized CORS policy
• Security headers (HSTS, CSP, X-Frame)
• connection-timeout and response-timeout set
• Multiple gateway instances behind ALB
• Prometheus metrics exposed
• Access log to structured JSON

@Configuration
public class LoanServiceRouteConfig {

    @Bean
    public RouteLocator loanServiceRoutes(RouteLocatorBuilder builder,
                                          JwtAuthenticationFilter jwtFilter) {
        return builder.routes()
            // Route new mobile clients (v3+) to loan-service-v2
            .route("loan-service-v2", r -> r
                .path("/api/v1/loans/**")
                .and().header("X-Client-Version", "3\\..*")  // regex: 3.x.x
                .filters(f -> f
                    .stripPrefix(2)
                    .addRequestHeader("X-Routed-By", "gateway-v2")
                    .filter(jwtFilter)
                    .circuitBreaker(c -> c
                        .setName("loan-service-cb")
                        .setFallbackUri("forward:/fallback/loans")))
                .uri("lb://loan-service-v2"))

            // All other clients go to stable loan-service-v1
            .route("loan-service-v1", r -> r
                .path("/api/v1/loans/**")
                .filters(f -> f
                    .stripPrefix(2)
                    .filter(jwtFilter)
                    .circuitBreaker(c -> c
                        .setName("loan-service-cb")
                        .setFallbackUri("forward:/fallback/loans")))
                .uri("lb://loan-service-v1"))
            .build();
    }
}

@Configuration
public class JwtConfig {

    @Bean
    public ReactiveJwtDecoder reactiveJwtDecoder(
            @Value("${spring.security.oauth2.resourceserver.jwt.jwk-set-uri}") String jwkUri) {
        // NimbusReactiveJwtDecoder caches JWKS for 5 minutes by default
        return NimbusReactiveJwtDecoder.withJwkSetUri(jwkUri)
            .cache(Cache.builder()
                .maximumSize(1)
                .expireAfterWrite(Duration.ofMinutes(5))
                .build())
            .build();
    }

    @Bean
    public Cache<String, JwtClaimsSet> jwtClaimsCache() {
        // Cache decoded JWT claims keyed by token fingerprint (first 32 chars of token)
        // Tokens expire in 15 min — cache for 14 min to avoid stale entries
        return Caffeine.newBuilder()
            .maximumSize(50_000)
            .expireAfterWrite(Duration.ofMinutes(14))
            .recordStats()
            .build();
    }
}

// In the GlobalFilter — check cache before decoding
public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    String token = extractToken(exchange);
    String cacheKey = token.substring(0, Math.min(32, token.length()));

    JwtClaimsSet cached = claimsCache.getIfPresent(cacheKey);
    if (cached != null) {
        return proceedWithClaims(exchange, chain, cached);  // cache hit — 0ms overhead
    }

    return jwtDecoder.decode(token)
        .flatMap(jwt -> {
            JwtClaimsSet claims = buildClaimsSet(jwt);
            claimsCache.put(cacheKey, claims);
            return proceedWithClaims(exchange, chain, claims);
        });
}

spring:
  cloud:
    gateway:
      routes:
        - id: loan-application-api
          uri: lb://loan-service
          predicates:
            - Path=/api/v1/loans/apply
          filters:
            - name: RequestRateLimiter
              args:
                # Per-user: 10 applications/minute, burst of 3
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 3
                redis-rate-limiter.requestedTokens: 1
                key-resolver: "#{@userIdKeyResolver}"
                # Fail open when Redis is unavailable (don't drop traffic)
                deny-empty-key: false

  data:
    redis:
      host: ${REDIS_HOST:redis-cluster.internal}
      port: 6379
      timeout: 200ms          # fast timeout — fail open if Redis is slow
      lettuce:
        pool:
          max-active: 20
          min-idle: 5
          max-wait: 100ms

@Component
@Order(Ordered.HIGHEST_PRECEDENCE + 5)
@Slf4j
public class RequestTracingAndLoggingFilter implements GlobalFilter {

    private static final String REQUEST_START_TIME = "requestStartTime";
    private static final String TRACE_ID_HEADER   = "X-Request-ID";

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        // 1. Generate or propagate trace ID
        String traceId = Optional.ofNullable(
            exchange.getRequest().getHeaders().getFirst(TRACE_ID_HEADER))
            .orElse(UUID.randomUUID().toString());

        // 2. Store start time for duration calculation
        exchange.getAttributes().put(REQUEST_START_TIME, System.currentTimeMillis());

        // 3. Attach trace ID to outbound request headers
        ServerHttpRequest mutatedRequest = exchange.getRequest().mutate()
            .header(TRACE_ID_HEADER, traceId)
            .build();

        return chain.filter(exchange.mutate().request(mutatedRequest).build())
            .then(Mono.fromRunnable(() -> {
                long duration = System.currentTimeMillis() -
                    (Long) exchange.getAttributes().get(REQUEST_START_TIME);

                String method = exchange.getRequest().getMethod().name();
                String path   = exchange.getRequest().getPath().value();
                int    status = exchange.getResponse().getStatusCode() != null
                                ? exchange.getResponse().getStatusCode().value() : 0;

                // 4. Sanitize — never log the raw Authorization header
                String authHeader = exchange.getRequest().getHeaders()
                    .getFirst("Authorization");
                String sanitizedAuth = sanitize(authHeader);

                log.info("method={} path={} status={} duration={}ms traceId={} auth={}",
                    method, path, status, duration, traceId, sanitizedAuth);

                // Propagate trace ID back to client response
                exchange.getResponse().getHeaders().add(TRACE_ID_HEADER, traceId);
            }));
    }

    /**
     * Masks the JWT payload — keeps the header (alg/typ) visible for debugging
     * but replaces the payload and signature with asterisks.
     * Example: "Bearer eyJhbGciOiJSUzI1NiJ9.***"
     */
    private String sanitize(String authHeader) {
        if (authHeader == null) return "none";
        if (!authHeader.startsWith("Bearer ")) return "[non-bearer]";
        String token = authHeader.substring(7);
        int firstDot = token.indexOf('.');
        if (firstDot < 0) return "Bearer [malformed]";
        return "Bearer " + token.substring(0, firstDot + 1) + "***";
    }
}

@Component
public class ErrorResponseLoggingFilter implements GlobalFilter, Ordered {

    @Override
    public int getOrder() { return Ordered.LOWEST_PRECEDENCE - 10; }

    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        return chain.filter(exchange).then(Mono.defer(() -> {
            HttpStatus status = (HttpStatus) exchange.getResponse().getStatusCode();
            if (status != null && status.isError()) {
                String traceId = exchange.getRequest().getHeaders()
                    .getFirst("X-Request-ID");
                log.warn("Error response: status={} path={} traceId={}",
                    status.value(),
                    exchange.getRequest().getPath().value(),
                    traceId);
            }
            return Mono.empty();
        }));
    }
}

@Component
public class PremiumUserRoutePredicateFactory
        extends AbstractRoutePredicateFactory<PremiumUserRoutePredicateFactory.Config> {

    @Autowired private UserTierService userTierService;

    public PremiumUserRoutePredicateFactory() {
        super(Config.class);
    }

    @Override
    public Predicate<ServerWebExchange> apply(Config config) {
        return exchange -> {
            // Extract user ID injected by JWT filter upstream
            String userId = exchange.getRequest().getHeaders()
                .getFirst("X-User-Id");
            if (userId == null) return false;
            // Check user tier — cached in Redis, <1ms lookup
            return userTierService.isPremium(userId);
        };
    }

    @Validated
    public static class Config {
        // No config params needed for this predicate
    }
}

// Usage in YAML:
// predicates:
//   - Path=/api/v1/loans/**
//   - PremiumUser=
// uri: lb://loan-service-premium

// application.yml — graceful shutdown
server:
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

# Kubernetes preStop hook (give in-flight requests time to complete)
# spec.containers.lifecycle:
#   preStop:
#     exec:
#       command: ["/bin/sh", "-c", "sleep 5"]

---
// FallbackController — entirely local, zero downstream calls
@RestController
public class GatewayFallbackController {

    @GetMapping("/fallback/loans")
    public ResponseEntity<Map<String, Object>> loansFallback(
            ServerWebExchange exchange) {
        String traceId = exchange.getRequest().getHeaders()
            .getFirst("X-Request-ID");
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
            .header("X-Request-ID", traceId)
            .header("Retry-After", "30")
            .body(Map.of(
                "error", "LOAN_SERVICE_UNAVAILABLE",
                "message", "The loan service is temporarily unavailable. Please retry in 30 seconds.",
                "traceId", traceId != null ? traceId : "unknown",
                "timestamp", Instant.now().toString()
            ));
    }

    @GetMapping("/fallback/user-service")
    public ResponseEntity<Map<String, Object>> userServiceFallback(
            ServerWebExchange exchange) {
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
            .body(Map.of(
                "error", "USER_SERVICE_UNAVAILABLE",
                "message", "User service is temporarily unavailable.",
                "timestamp", Instant.now().toString()
            ));
    }
}