Spring Reactive API Gateway
WebFlux, Eureka-powered routing, and JWT border security
In a monolithic application, clients communicate with a single backend endpoint. Authentication, routing, monitoring, and business logic all reside within the same deployable unit.
Microservices fundamentally change this model.
A modern platform may expose dozens of independent services responsible for users, payments, notifications, reporting, search, and more. Exposing every service directly to clients introduces significant operational and security challenges. Frontend applications must understand service locations, authentication requirements, versioning strategies, and deployment changes.
This creates tight coupling between consumers and infrastructure.
An API Gateway solves this problem by acting as the single-entry point for all external traffic. Clients communicate with one endpoint while the gateway handles authentication, routing, service discovery, traffic management, and observability.
In this article, we’ll explore how Spring Cloud Gateway provides a reactive, non-blocking gateway layer capable of securing and routing traffic across a distributed Spring Boot microservices platform.
Why API Gateways Exist
Without an API Gateway, every client must know:
- Where services are located
- Which authentication mechanism each service uses
- Which versions are available
- Which endpoints are public
- Which endpoints require authorization
As systems grow, maintaining this knowledge becomes increasingly difficult.
An API Gateway centralizes these concerns.
Instead of:
- Frontend – User Service
- Frontend – Payment Service
- Frontend – Notification Service
Clients interact with:
- Frontend – API Gateway
The gateway becomes responsible for:
- Authentication
- Authorization
- Service discovery
- Routing
- Logging
- Monitoring
- Rate limiting
- Request transformation
This simplifies client applications and provides a strategic control point for operational concerns.
Why We Chose Spring Cloud Gateway
Several gateway technologies exist today. Common options include:
- Spring Cloud Gateway
- Kong
- NGINX
- Traefik
- Envoy
For this platform, Spring Cloud Gateway was selected because it integrates naturally with:
- Spring Security
- Eureka
- OAuth2 Resource Server
- Spring Cloud LoadBalancer
More importantly, it is built on Spring WebFlux and Project Reactor, allowing requests to be processed using a non-blocking execution model.
This makes it particularly suitable for handling large numbers of concurrent connections while maintaining efficient resource utilization.
Spring Cloud Gateway vs Alternatives
| Capability | Spring Gateway | Kong | NGINX |
|---|---|---|---|
| Spring Integration | Excellent | Limited | Limited |
| Reactive Architecture | Yes | No | No |
| Service Discovery | Native | Plugin Based | Manual |
| OAuth2 Integration | Excellent | Good | Custom |
| Kubernetes Support | Good | Excellent | Excellent |
| Learning Curve | Low | Medium | Medium |
The correct choice depends on operational requirements, team expertise, and infrastructure maturity.
Gateway Responsibilities
An API Gateway should focus on infrastructure concerns. Typical responsibilities include:
- Authentication: Validating access tokens before requests reach backend services.
- Routing: Determining which service should receive the request.
- Service Discovery: Resolving service locations dynamically.
- Request Logging: Providing a central audit trail.
- Traffic Policies: Enforcing rate limits and quotas.
- Observability: Collecting metrics and tracing information.
What Should NOT Live in a Gateway
One of the most common mistakes in microservice platforms is allowing business logic to migrate into the gateway.
A gateway should not:
- Execute business workflows
- Access databases
- Perform payment processing
- Apply domain-specific rules
- Become an orchestration engine
These responsibilities belong to downstream services. The gateway should remain an infrastructure component.
When business logic enters the gateway, it quickly becomes a bottleneck that is difficult to scale, test, and maintain.
Architecture & Tech Stack
| Component | Details |
|---|---|
| Language & Framework | Java 21 & Spring Boot 4.0.3 |
| Framework | Spring Cloud Gateway (WebFlux/Netty) |
| Service Discovery | Eureka Client — dynamic service resolution via lb:// URIs |
| Security | Reactive Spring Security — OAuth2 Resource Server with RS256 JWT validation |
| Routing | Declarative YAML-based route definitions with StripPrefix filters |
Suggested Architecture Diagram
Traditional Architecture
Problems:
- Multiple endpoints
- Duplicate security
- Client complexity
Gateway Architecture
Dependencies
To build the API Gateway using Spring Cloud Gateway, Spring WebFlux, and Spring Security, include the following dependencies.
<dependencies>
<!-- Spring Cloud Gateway (Reactive) -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
</dependency>
<!-- Eureka Client -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>
<!-- Load Balancer -->
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>
<!-- Security -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-security</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-actuator</artifactId>
</dependency>
<!-- OAuth2 Resource Server -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
<!-- Test -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
Declarative Routing — application.yml
All routing logic is externalized to YAML. Adding a new microservice requires exactly five lines of configuration — no Java code changes.
spring:
cloud:
gateway:
discovery:
locator:
enabled: true
lower-case-service-id: true
server:
webflux:
routes:
- id: user-service
uri: lb://USER-SERVICE
predicates:
- Path=/user-service/**
filters:
- StripPrefix=1
- id: payment-service
uri: lb://PAYMENT-SERVICE
predicates:
- Path=/payment-service/**
filters:
- StripPrefix=1
How StripPrefix Works
When the frontend sends GET /user-service/api/v1/users, the Predicate matches /user-service/**. StripPrefix=1 removes the /user-service segment. The Gateway asks Eureka for USER-SERVICE‘s IP and forwards the request to http://10.0.1.4:8080/api/v1/users.
Security at the network border
A key design principle of this platform is validating authentication as early as possible.
Rather than allowing requests to travel through the network before discovering they are unauthorized, JWT validation occurs at the gateway itself.
This provides several benefits:
- Reduced Internal Traffic: Invalid requests never reach backend services.
- Improved Security: Unauthorized traffic is blocked at the perimeter.
- Consistent Enforcement: Authentication rules are applied centrally.
- Operational Simplicity: Backend services can assume authentication has already been verified.
This pattern is often referred to as border authentication and is commonly used in zero-trust architectures.
Reactive JWT Security – SecurityConfig.java
The Gateway validates JWT tokens at the network border before requests to touch downstream services. Public endpoints (login, signup, webhooks) are explicitly whitelisted.
@Configuration
@EnableWebFluxSecurity
public class SecurityConfig {
private static final String[] PUBLIC_ENDPOINTS = {
"/authorization-server/api/v1/auth/login",
"/user-service/api/v1/users/create",
"/user-service/api/v1/forget-password/**",
"/payment-service/webhook/**",
"/actuator/**"
};
@Bean
public SecurityWebFilterChain securityFilterChain(ServerHttpSecurity http) {
http
.csrf(ServerHttpSecurity.CsrfSpec::disable)
.authorizeExchange(exchanges -> exchanges
.pathMatchers(PUBLIC_ENDPOINTS).permitAll()
.anyExchange().authenticated())
.oauth2ResourceServer(oauth2 -> oauth2
.jwt(jwt -> jwt.jwtAuthenticationConverter(
grantedAuthoritiesExtractor())));
return http.build();
}
}
Request Lifecycle
A request passing through the gateway follows these stages:
1. Client sends request.
2. Gateway validates JWT.
3. Gateway evaluates routing rules.
4. Gateway resolves destination through Eureka.
5. Spring Cloud LoadBalancer selects an instance.
6. Request is forwarded.
7. Response returns through gateway.
This entire process occurs without the client needing awareness of backend topology.
Production Considerations
Rate Limiting
Public-facing APIs should implement rate limits to prevent abuse and accidental overload. Spring Cloud Gateway supports both Redis-backed and custom rate limiting strategies.
Typical use cases include
- Login endpoints
- Payment APIs
- Public integrations
Distributed Tracing
As requests to traverse multiple services, troubleshooting becomes increasingly difficult. Gateways should generate correlation identifiers that travel through every downstream request.
This allows engineering teams to reconstruct complete request paths across the platform.
Observability
At minimum, collect:
- Request count
- Error rate
- Latency
- Route utilization
- Authentication failures
The gateway often provides the most accurate view of platform traffic.
High Availability
The gateway is a critical infrastructure component. Production deployments should run multiple gateway instances behind a load balancer to eliminate single points of failure.
SSL Termination
Most production environments terminate TLS at the gateway. This centralizes certificate management and simplifies backend service configuration.
Future Enhancements
The current gateway implementation provides routing and authentication. Future capabilities may include:
- Rate Limiting: Prevent abuse and traffic spikes.
- Canary Releases: Route small percentages of traffic to new versions.
- Blue-Green Deployments: Reduce deployment risk.
- Response Caching: Improve latency for frequently accessed resources.
- Web Application Firewall Integration: Provide additional protection against malicious traffic.
Conclusion
The API Gateway is far more than a routing component. It serves as the control plane for inbound traffic, enforcing security policies, simplifying service communication, and providing operational visibility across the platform.
By combining Spring Cloud Gateway, Spring Security, and Eureka Service Discovery, we establish a centralized entry point capable of validating authentication, resolving service locations dynamically, and routing requests efficiently across a distributed architecture.
As platforms grow, the gateway becomes increasingly valuable. Features such as rate limiting, tracing, traffic shaping, and centralized observability all naturally build upon this foundation.
When designed correctly, the gateway allows backend services to focus entirely on business capabilities while infrastructure concerns remain centralized and consistent.
Source Code: https://github.com/inexture-solutions/springboot-microservices/tree/main/api-gateway
FAQs
Why not expose services directly?
Direct exposure increases security risk and couple’s clients to infrastructure details. An API Gateway abstracts service locations and centralizes security enforcement.
Does every request go through the gateway?
External requests typically do. Internal service-to-service communication may bypass the gateway depending on architecture requirements.
Is Spring Cloud Gateway suitable for high traffic systems?
Yes. Because it is built on WebFlux and Netty, it can efficiently handle large numbers of concurrent requests using a non-blocking architecture.
Should authorization also happen at the gateway?
Authentication should almost always occur at the gateway. Authorization may occur at both gateway and service layers depending on security requirements.
Can Spring Cloud Gateway replace a load balancer?
Not entirely. Gateway routing and infrastructure load balancing solve different problems and often work together.
