Trusted Proxies

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 use these settings if any of the following statements are true about your WHMCS installation:

  • It is behind a proxy that you control.
  • It is behind a load balancer or firewall that modifies HTTP requests.
  • It receives HTTP requests from a proxy or DDOS protection service like CloudFlare® or BlackLotus.
  • It is behind infrastructure that modifies the information in the link layer of a request.

These types of deployment setups will alter the value from the originating IP address to their own IP address. This is expected behavior. Unfortunately, if you do not counteract this alteration, your client logins, admin logins, and orders all appear to come from the same place. Logging, access authorization, fraud detection, and other IP-related tasks will have no way to access the real locations.

Mitigating the Effects of Proxies As A Host

You can choose between two strategies to resolve this issue:

Install a Webserver Module

Install a webserver module that checks whether the inbound request is from a trusted forwarding source and automatically manages the information appropriately prior to releasing the request to the handler (for example, asking your application to respond to the request).

  • Some hosting providers already include this in their infrastructure and provisioning. For more information on available options, contact your hosting provider.
  • If you manage your own server, you can use a service provider outside of your network and compile a webserver module to adjust your IP information appropriately.

For example, you could use the mod_cloudflare module to rewrite IP information if the request came from a CloudFlare IP address. It allows you to add additional IP address ranges to observe.

Consult an Admin-Managed List of Trusted Sources

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

You can set your Trusted Proxy settings in the Security tab at Configuration () > System Settings > General Settings. A trusted proxy is a network device which you control (or to which you subscribe) that will 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.
    The Trusted Proxies setting in General Settings

Last modified: June 14, 2024