Rate Limiting With Client IP in Spring Cloud Gateway

1. Introduction

In this quick tutorial, we’ll see how to limit the rate of incoming requests based on the client’s actual IP address for our Spring Cloud Gateway.

In short, we’ll set up the RequestRateLimiter filter on a route, then we’ll configure the gateway to use the IP address for limiting requests by unique clients.

2. Route Configuration

First, we need to configure Spring Cloud Gateway to rate limit a specific route. For this, we’ll use a classic token-bucket rate limiter implemented by spring-boot-starter-data-redis-reactive. In short, the rate limiter creates a bucket with an associated key that identifies itself and a fixed initial capacity of tokens that get replenished over time. Then, for each request, the rate limiter checks its related bucket and reduces a token if possible. Otherwise, it denies the incoming request.

As we’re working with distributed systems, we might want to keep track of all the incoming requests across all the instances of our application. For this reason, having a distributed cache system is convenient for storing the bucket’s information. In this case, we pre-configured a Redis instance to simulate a real-world application.

Next, we’ll configure a route with a rate limiter. We’ll listen to the /example endpoint and forward the request to http://example.org:

@Bean
public RouteLocator myRoutes(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("requestratelimiter_route", p -> p
            .path("/example")
            .filters(f -> f.requestRateLimiter(r -> r.setRateLimiter(redisRateLimiter())))
            .uri("http://example.org"))
        .build();
}

Above, we configure the route with a RequestRateLimiter by using the .setRateLimiter() method. In particular, we define the RedisRateLimiter bean through the method redisRatelimiter() to manage the state for our rate limiter:

@Bean
public RedisRateLimiter redisRateLimiter() {
    return new RedisRateLimiter(1, 1, 1);
}

As an illustration, we configure the rate limit with all replenishRate, burstCapacity, and requestedToken attributes set to 1. This makes it easy to call the /example endpoint multiple times and to get back the HTTP 429 response code.

3. The KeyResolver Bean

To work correctly, the rate limiter must identify each client hitting the endpoint through a key. Underneath, the key identifies the bucket the rate limiter will use to consume tokens for each request. So, we want the key to be unique for each client. In this case, we’ll use the client’s IP address to monitor their requests and limit them if they make too many requests.

So, the RequestRateLimiter we configured previously will use a KeyResolver bean that allows pluggable strategies to derive the key for limiting requests. This means we can configure how the key is extracted from each request.

4. Client’s IP Address in KeyResolver

Currently, there is no default implementation for this interface, so we must define one, keeping in mind that we want the client’s IP address:

@Component
public class SimpleClientAddressResolver implements KeyResolver {
    @Override
    public Mono<String> resolve(ServerWebExchange exchange) {
        return Optional.ofNullable(exchange.getRequest().getRemoteAddress())
            .map(InetSocketAddress::getAddress)
            .map(InetAddress::getHostAddress)
            .map(Mono::just)
            .orElse(Mono.empty());
    }
}

We’re using the ServerWebExchange object to extract the client’s IP address. If we can’t get the IP address, we’ll return Mono.empty() to signal this to the rate limiter and deny the request by default. However, we can configure the rate limiter to allow requests when the KeyResolver returns an empty key by setting .setDenyEmptyKey() to false. Moreover, we can also have a different KeyResolver for each different route by providing a custom KeyResolver implementation to the .setKeyResolver() method:

builder.routes()
    .route("ipaddress_route", p -> p
        .path("/example2")
        .filters(f -> f.requestRateLimiter(r -> r.setRateLimiter(redisRateLimiter())
            .setDenyEmptyKey(false)
            .setKeyResolver(new SimpleClientAddressResolver())))
        .uri("http://example.org"))
.build();

4.1. Originating IP Address When Behind a Proxy

The previously defined implementation works if Spring Cloud Gateway listens directly to the client’s request. However, if we deploy the application behind a proxy, all the host addresses will be the same. Therefore, the rate limiter will see all requests as coming from the same client and limit the number of requests it can handle.

To solve this problem, we rely on the X-Forwarded-For header to identify the originating IP address of a client connecting through a proxy server. For example, let’s configure the KeyResolver so it can read the originating IP address:

@Primary
@Component
public class ProxyClientAddressResolver implements KeyResolver {
    @Override
    public Mono<String> resolve(ServerWebExchange exchange) {
        XForwardedRemoteAddressResolver resolver = XForwardedRemoteAddressResolver.maxTrustedIndex(1);
        InetSocketAddress inetSocketAddress = resolver.resolve(exchange);
        return Mono.just(inetSocketAddress.getAddress().getHostAddress());
    }
}

We are passing the value 1 to maxTrustedIndex(), assuming we only have one proxy server. Otherwise, the value must be set accordingly. Further, we annotate this KeyResolver with @Primary to give it precedence over the previous implementation.

5. Conclusion

In this article, we configured an API rate limiter based on the client’s IP address. First, we configured a route with a token-bucket rate limiter. Then, we explored how the KeyResolver identifies the bucket used for each request. Finally, we explored strategies for assigning the client’s IP address through the KeyResolver when hitting our API directly or when it is deployed behind a proxy.