X Forwarded For

When a client establishes a direct connection to a server, the client’s IP address is transmitted to the server, often being recorded in server access logs. If the connection passes through any forward or reverse proxies, the server typically only detects the final proxy’s IP address, which may be of limited utility. This issue becomes more pronounced if the final proxy is a load balancer within the same deployment as the server.

To transmit a more accurate client IP address to the server, the X-Forwarded-For request header is employed. For detailed instructions on utilizing this header, refer to the sections on parsing and selecting an IP address.

Security and privacy concerns

This header exposes sensitive privacy information by design, so it is crucial to handle it with care. If all proxies in the request chain are trusted and correctly configured, the parts of the header added by these proxies can be trusted. However, if any proxy is malicious or misconfigured, spoofing or incorrect data may occur, rendering parts of the header unreliable. Even when behind a trusted reverse proxy, the server cannot fully trust X-Forwarded-For IPs if a direct internet connection exists. Any security-related features such as rate limiting or IP-based controls should only rely on IPs added by trusted proxies. Using untrustworthy IPs can lead to bypassed restrictions, security vulnerabilities, or system overloads.

Untrusted, leftmost IP values should only be used in situations where their potential for spoofing does not pose security risks.

Parsing

Improper parsing of the X-Forwarded-For header can have security implications, including those mentioned earlier. Consider these points when parsing: multiple X-Forwarded-For headers may be present; their IPs should be treated as a sequence starting from the first IP in the first header to the last IP in the last header. To form this sequence, either join all header values with commas and split by comma or split each header individually and then combine the lists. Using only one header is insufficient, as some proxies may join multiple headers automatically, but this behavior should not be assumed.

Selecting an IP address

When choosing an IP address from the complete list, it must include all IPs from all X-Forwarded-For headers. The closest to the client (not for security use) can be the first valid, non-private IP from the leftmost position. Note that spoofed values may not be actual IP addresses, and internal client networks may have added addresses from private IP spaces.

To select the first trustworthy client IP, additional configuration is necessary, typically one of two methods:

Trusted proxy count

The number of reverse proxies between the internet and the server is configured. The IP list is examined from the right, skipping the number of proxies minus one. For example, with one proxy, the rightmost IP is the client; with three proxies, the last two IPs are internal and should be ignored.

Trusted proxy list

The IP addresses or ranges of trusted proxies are configured. The list is searched from the right, skipping addresses on this list. The first non-trusted address from the right is considered the client IP.

Although the first trustworthy X-Forwarded-For IP might belong to an intermediate, untrusted proxy, it remains the most reliable identifier of the client for security purposes.