GATEWAY

This service acts as the API Gateway and sole entry point in a microservice ecosystem. Built on the reactive Spring Cloud Gateway (WebFlux) framework, it provides high-throughput, non-blocking edge routing, load balancing, multi-tenant context enrichment, and frontline security enforcement.

Technology Stack & Compatibility

• Java Version: 17
• Spring Boot Version: 3.5.5
• Spring Cloud Release Train: 2025.0.0
• Build Tool: Maven
• Core Dependency: spring-cloud-starter-gateway-server-webflux
• Security Dependencies: spring-boot-starter-security, spring-boot-starter-oauth2-resource-server
• Internal Dependency: shared-service
• Compatibility Matrix: Fully compatible with Spring Boot 3.5.x and Java 17+

Key Features

Security & Token Validation

As the edge proxy, this application is configured as an OAuth2 Resource Server validating stateless JSON Web Tokens (JWTs).

• Token Verification: Automatically handled via a JSON Web Key Set (JWKS) endpoint.
• Reactive Adapter: Utilizes ReactiveJwtAuthenticationConverterAdapter to extract claims from the JWT payload and map them directly to standard Spring Security GrantedAuthority roles.
• Traffic Reduction: Requests missing a valid JWT, failing CSRF verification, or violating CORS policies are blocked immediately at the edge. This protects downstream microservices from processing unauthorized or malicious traffic.

Custom Gateway Filter Chain

Routing logic goes beyond basic path forwarding. Employed a custom MyGatewayFilter (implemented via GatewayFilter) applied explicitly inside a RouteLocator bean.

The gateway filter sequence enforces the following pipeline:

• Header Validation & Guardrails: Validates that all mandatory headers are present on the incoming request (e.g., verifying the presence of the required X-XSRF-TOKEN, tenant identifiers, or expected metadata). If any required header is missing, the request is immediately rejected with an appropriate HTTP error status (e.g., 400 Bad Request or 403 Forbidden) without forwarding.
• Authentication Double-Check: Validates the presence and validity of the security context.
• Authorization: Checks user roles/scopes against the target path.
• Downstream Routing: Forwards the mutated request to the target destination.

Configuration and Code Implementation

Identity Provider (IdP) Setup

Configure the application properties to locate the JWKS endpoint used to decode and verify signatures:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          jwk-set-uri: https://auth-server.com/auth/.well-known/jwks.json

CORS & CSRF Mitigation

Because this is a web-facing boundary, strict cross-origin rules apply:

• CORS: Handled via a global CorsWebFilter bean to manage cross-origin traffic explicitly.
• CSRF: Configured using a cookie-backed repository optimized for Single Page Applications (SPAs).

Security Configuration

The gateway maintains a stateless SecurityWebFilterChain incorporating a global CorsWebFilter bean and cookie-backed CSRF mitigation optimized for Single Page Applications (SPAs).

Because standard Spring Security CSRF tokens are deferred (lazy) by default in reactive environments, a custom WebFilter is placed in the pipeline to explicitly subscribe to and flush the token cookie (CookieServerCsrfTokenRepository) on the client's initial metadata GET request.

// Conceptualized CSRF & Filter configuration within Configuration file
.csrf(csrf -> csrf
    .csrfTokenRepository(cookieServerCsrfTokenRepository()) // Bean method name
    .csrfTokenRequestHandler(new ServerCsrfTokenRequestAttributeHandler())
)

Filter Ordering: The custom CSRF activation filter is configured to execute immediately after SecurityWebFiltersOrder.CSRF to ensure it successfully forces token generation.

Dynamic Route Routing

Routes are explicitly managed as Java beans rather than raw configuration files to cleanly embed the custom filter logic.

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder, MyGatewayFilter gatewayFilter) {
    return builder.routes()
            .route("portfolio-service", r -> r.path("/portfolio/**")
                    .filters(f -> f.filter(gatewayFilter))
                    .uri("https://my-portfolio.com")
            )
            .build();
}

Project Structure

├───config/ #SecurityWebFilterChain, CorsWebFilter, CSRF and RouteLocator beans configured
├───filters/ #CSRF filter to trigger a token, Gatewat filter to validate authentication, authorization, tenant-info
└───properties/ #Java 17 configuration records

Decision Log (Architecture Decision Records)

ADR 1: WebFlux over Spring MVC

• Context: Gateway applications handle massive concurrency while waiting on I/O responses from downstream microservices.
• Decision: Leverage spring-cloud-starter-gateway-server-webflux built on Netty.
• Consequence: BlockHound or reactive paradigms must be adhered to. Traditional ThreadLocal cannot be used safely for multi-tenancy context propagation.

ADR 2: Java Route Definitions over YAML

• Context: Routes require deep integration with a highly specific, imperative custom filter (MyGatewayFilter).
• Decision: Define all paths using the fluent RouteLocator Java API.
• Consequence: Changing routes requires a application rebuild/redeploy, but guarantees strict type-safety and robust filter ordering.

ADR 3: Edge-Enforced Multi-Tenancy Guardrails

• Context: Downstream microservices rely entirely on the gateway to provide a trusted tenant context. Processing a request without a specific tenant context can cause data leakage or critical errors across the microservice mesh.
• Decision: Implement an aggressive "Fail-Fast" check at the gateway filter entry point. The gateway validates the presence of the tenant header before any authentication double-checks or authorization evaluations occur.
• Consequence: Requests missing the mandatory multi-tenant identifiers are dropped instantly with an HTTP 400 Bad Request or 403 Forbidden status. This completely shields downstream applications from un-scoped multi-tenant traffic and minimizes unnecessary computing overhead.

Troubleshooting

Tracking Routing Decisions

If traffic is returning 404 Not Found or hitting the incorrect microservice, elevate the logging thresholds in local configuration profile to expose the gateway's internal evaluation pipeline:

logging:
  level:
    org.springframework.cloud.gateway: TRACE
    org.springframework.security: DEBUG

Missing CSRF Cookie on Initial Load

If front-end applications fail because of a missing XSRF-TOKEN cookie, verify that the client application sends an initial metadata GET request. The custom CsrfFilter will not flush the cookie to the client until a subscription is explicitly triggered on that initial connection loop.

Future Enhancements

• Migration of the SecurityWebFilterChain, CorsWebFilter, and generalized security definitions out of this local project and directly into the internal shared library (shared-service). This will ensure that if additional gateway instances are spun up for other sub-domains, security protocols remain identical.