Client IP address override

Extension for applying the protection: x-42c-set-client-ip_0.1

You apply protections to your API as strategies by using the x-42c security extensions, either locally to specific paths, operations, responses, or HTTP status codes, or alternatively to all incoming requests or outgoing responses. For more details, see Protections and security extensions.


This protection lets you override the value of client.ip when API Firewall processes other protections.

The protection requires API Firewall image v1.0.12 or higher.

For example, the traffic to your API could pass through an ingress controller in your Kubernetes deployment — or a load balancer and proxies — before it gets to API Firewall. As the request traverses through the system, the visible client IP address gets changed to point to your internal systems, while the original IP address is stored in a header (such as X-Forwarded-For or X-Real-IP). With this protection, API Firewall can retrieve the original IP address from that header and use it as the value for client.ip, instead of simply taking the IP address from where the request arrived to API Firewall itself. This way, the checks from other protections that API Firewall might perform are based on the correct IP address.

To prevent attackers from forging the headers at the client level and faking the origin of the API call, we recommend that you also define an allowlist of IP addresses or address ranges for those internal components in your system that are allowed to add the header. By default, this list is empty, but for security reasons we recommend that you add at least one IP address in your system (such as the IP address of you load balancer or ingress controller) to the list, regardless if the deployment is for production or not.

This policy can be especially useful when your API is protected with rate limiting. If your rate limiting would allow increased rate for internal IP addresses, it could be important to distinguish calls that originated outside your system. You can also use it in conjunction with x-42c-access-control-based-on-ip-range_0.1, see Access control based on IP address range.


You can configure the following parameters:

Parameter name Description Required. The name of the header from which API Firewall should take the value of the client IP address (for example, X-Forwarded-For or X-Real-IP).

Required. Is the header mandatory or not. The default value is true.

  • If the header is set to be mandatory (true) but it is not present in the request, the request is blocked.
  • If the header is not mandatory (false) and it is not present in the request, the protection automatically accepts the API call.

This is to accommodate the fact that an API could be exposed both internally and externally: when exposed internally, the header would not be present, whereas externally it would.

remote.ip.allowlist List of IP addresses (in CIDR notation, both IPv4 and IPv6 are supported) of the internal components (such as ingress controllers, load balancers, or proxies) that are allowed to set the header where the original client IP value is stored. If defined, API Firewall blocks requests that have the header set but are arriving from other IP addresses. This parameter is optional, but for security reasons we recommend adding at least one IP address in your system to the list.


                - x-42c-set-client-ip_0.1:
                    ip.header.mandatory: true
                # ...