The XFF HTTP request header is a de facto standard header that contains the IP address of a client that connects to a server via a proxy server.

When a client makes a request to a server, the server observes the source IP address of the connection. But when a proxy sits in between, the server sees the proxy’s address as its connection peer, where the proxy may preserve the original client address in this header.

Note

The standardized version of X-Forwarded-For is the Forwarded HTTP request header.

See developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded.

Format

X-Forwarded-For: <client>, <proxy1>, <proxy2>, ...

In the common append model, each proxy adds the address of the peer from which it received the request. The first value is the original client’s address, assuming the chain is well behaved.

So the rightmost XFF value is the address observed by the final proxy. The final proxy’s own address is the server’s connection peer. With just one proxy between the client and server, the header contains the client’s address.

Parsing multiple XFF headers

There can be multiple XFF headers present in a request.

When this happens, the IP addresses in all headers must be treated as a single list: starting with the first IP address of the first header and continuing to the last IP address of the last header.

Essentially, you must concatenate all XFF header values.

Warning

It is insufficient to only use one XFF header when multiple are present.

Security

The XFF header is untrustworthy unless the request arrived through a verified trusted proxy and the proxy is configured to append or overwrite the header correctly. Any requests that reach the origin directly must be treated as untrusted, regardless of their XFF header. Restricting origin access to your proxies helps enforce this boundary. Leftmost untrusted values must only be used when there’s no risk of using potentially “spoofed” values.

Start with the connection peer and walk the addresses from right to left, skipping proxies in your trusted list. Use the first untrusted address for security-related uses, like rate-limiting or blocking requests. A trusted hop count can also work, but only when every permitted path has the expected number of proxies.

Privacy

Because the XFF header exposes privacy-sensitive information (the IP address of a client), the user’s privacy must be kept in mind when using this header.

Resources