Identifying Clients from HTTP Headers and Request Context

Your learning outcome for this lesson:

You will learn to extract client identifiers from HTTP headers and the request context. By the end of this lesson, you'll understand how to inspect an incoming request in a Spring Boot application to pull out the pieces of information needed to uniquely identify a client.

1. The Source of Truth: HttpServletRequest

In a Java web application built on the servlet standard, like our Spring Boot project, every incoming HTTP request is represented by an object that implements the HttpServletRequest interface. This object is a treasure trove of information, containing everything from the request URL and headers to the client's IP address.

As you'll recall from Module 1, we created a RateLimitingInterceptor. Its preHandle method is perfectly positioned to inspect the request before it reaches your controller. The preHandle method conveniently receives the HttpServletRequest as an argument.

To learn about the most common methods we'll use, please read the following sections from a Baeldung article.

As you've just read, we can access critical information using simple method calls within our interceptor:

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.servlet.HandlerInterceptor;

public class RateLimitingInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // Example: Get the client's IP address
        String ipAddress = request.getRemoteAddr();

        // Example: Get a custom API key header
        String apiKey = request.getHeader("X-API-KEY");

        // Example: Get the requested endpoint path
        String requestUri = request.getRequestURI();

        System.out.println("Request from IP: " + ipAddress + " with API Key: " + apiKey + " to " + requestUri);

        // In future lessons, we will use this info to generate a key and check the rate limit.
        // For now, we just allow the request to proceed.
        return true; 
    }
}

These methods are the building blocks for all our key resolution strategies. However, there's a critical real-world complication with request.getRemoteAddr().

2. The Proxy Problem and the X-Forwarded-For Header

In almost any production environment, your application won't be exposed directly to the internet. It will sit behind one or more reverse proxies, load balancers (like AWS ALB or Nginx), or API gateways.

When a request passes through a proxy, the proxy terminates the original TCP connection from the client and establishes a new connection to your application server. This means that from your application's perspective, the request is coming from the proxy's IP address. If you use request.getRemoteAddr(), you'll get the IP of the load balancer, not the actual user. This would cause all users to share a single rate limit bucket—a critical failure.

To solve this, proxies add a standard HTTP header, X-Forwarded-For, which contains the IP address of the original client.

The following video provides an excellent explanation of this problem and its solution.

To build a robust IP resolver, you must always check for the X-Forwarded-For header first and fall back to getRemoteAddr() only if it's not present.

A reliable implementation looks like this:

private String getClientIpAddress(HttpServletRequest request) {
    String xffHeader = request.getHeader("X-Forwarded-For");
    if (xffHeader == null || xffHeader.isEmpty()) {
        // If the header is missing, fall back to the remote address.
        return request.getRemoteAddr();
    }
    
    // The X-Forwarded-For header can be a comma-separated list of IPs.
    // The first IP in the list is the original client's IP.
    return xffHeader.split(",")[0].trim();
}

This logic is essential for any service intended to run in a modern, containerized, or cloud-native environment.

3. Applying Extraction Logic in the Interceptor

We've established that our RateLimitingInterceptor is the right place to perform this logic. While we could put all our key-generation code directly in the preHandle method, that would lead to a monolithic and inflexible design.

As we designed in Module 2, our goal is to use a RateLimitKeyResolver interface, allowing us to swap out different key-generation strategies. The interceptor's job is simply to call the configured resolver.

The following article reinforces how a HandlerInterceptor is the ideal place for this kind of cross-cutting concern.

The logic inside the interceptor's preHandle method will look something like this conceptually:

1. Receive the HttpServletRequest.
2. Pass the request object to an active RateLimitKeyResolver implementation.
3. The resolver implements the specific logic (e.g., getting the IP, getting an API key header) and returns a String key.
4. The interceptor uses this key to call the isAllowed(key) method on the appropriate RateLimiter.

This elegant separation of concerns is what will make our final engine so powerful and maintainable.

Key Takeaways

• The HttpServletRequest object is our primary source for client information in a Spring Boot web application.
• We can access the client's IP, headers, and request path using methods like getRemoteAddr(), getHeader(), and getRequestURI().
• In a production environment behind a proxy or load balancer, you must check the X-Forwarded-For header to get the true client IP address.
• Our RateLimitingInterceptor is the ideal component to access the HttpServletRequest and delegate the task of key generation to a specialized RateLimitKeyResolver.

Next Steps

You now have the foundational knowledge to pull any piece of data you need from an incoming request. In our next lesson, we will put this into practice by implementing our first concrete RateLimitKeyResolver: one that extracts a client's API key from a custom HTTP header.