Trusted Proxy Settings

The Trusted Proxies setting allows you to itemize IP addresses or IP ranges for proxies or other forwarding services so that WHMCS can accurately determine the IP address of inbound traffic.

You may find it necessary to utilize the Trusted Proxy settings if your WHMCS installation:

• is behind a proxy you control
• is behind a load balancer or firewall that modifies HTTP requests
• receives HTTP requests from a proxy or DDOS protection service, such as CloudFlare, BlackLotus, etc
• is behind most any infrastructure which has the responsibility of modifying the information the link layer of a request.

These types of deployment setups will alter the value from the originating IP address to their own IP. This is expected behavior as it is part of standard network specifications. Unfortunately, there’s a side effect. This alteration, if not counteracted, makes it look as if your client logins, admin logins, and orders are all coming from the same place instead of the real location. When this happens, the location is masked from your inspection, be it for logging, access authorization, fraud detection, or any other IP related purposes.

Mitigating the Effects of Proxies As A Host

There are essentially two strategies available to you to counteract this side-effect.

• Install a webserver module that is responsible for observing the inbound request is from a trusted forwarding source and automatically managing the information appropriately prior to releasing the request to the handler (i.e., asking your application to respond to the request).

Some hosting providers have this kind of value-added extra already baked in to their infrastructure and provisioning. For the host, the entire process is completely transparent and there is no action required on your part.

Sometimes individuals or companies will have an entire server that they manage themselves. Often they may use a service provider, like CloudFlare, that is outside of their network. There are a number of Apache (and other webserver) modules that can be compiled and loaded as part of the webserver configuration to adjust the IP information appropriately. For instance, the mod_cloudflare module will rewrite IP information if the request can from an IP owned and operated by CloudFlare; it allows you to add additional IP ranges to observe.

• In the application code, very early in the runtime process, when determining the IP of the request (for authentication logs or order origin, etc), consult an admin-managed list for trusted forwarding sources. If the value of the IP is one of the trusted sources, then look to a different request header for the IP. The trusted source will have place the actual IP in a mutually agreed upon, trusted location. Most of the time that will be the ‘X_FORWARDED_FOR’ header, but it can may be different.

The downside to using an application code strategy is the webserver’s access log will still contain the address of the proxy, not the untrusted address.

If you use a webserver module based strategy, you almost certainly would not need to use an application based strategy; one strategy is all that is required to mitigate the impact that a proxy would have from WHMCS’s inspection of the IP address of the visitor.

Configuring Trusted Proxies in WHMCS

Set Trusted Proxy settings in the Security tab at Configuration () > System Settings > General Settings or, prior to WHMCS 8.0, Setup > General Settings. A trusted proxy is a network device which you control (or to which you subscribe services to, such as CloudFlare) who is trusted to correctly append the IP address of the original user to the IP stack.

You can configure two trusted proxy settings:

• Proxy IP Header — Configure the HTTP header to use to find the authoritative IP address for the request.
  • Most proxies use X_FORWARDED_FOR.
  • Only change this value if you are sure your proxy uses a different header, as putting the wrong header into this field can cause improper recording of IP addresses.
• Trusted Proxy List — Add and remove IP addresses and IP address CIDR ranges as trusted proxies and WHMCS will check the header configured to discover the actual canonical request IP address. This is useful for product logging.