Trusted Proxy Settings

Overview

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

Trusted Proxy settings are set in Setup > General Settings > Security tab. 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.

Proxy Header

The Proxy Header field allows you to configure the HTTP header WHMCS will use to figure out which IP address is 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

You can 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" IP address box allows you to configure these IP addresses in the product:

Adding an IP address or CIDR range

To add an IP address click the "Add IP" link under Trusted Proxies. In the modal dialog box that pops up, enter the IP address or CIDR range you wish to trust. You can also add an admin note to describe the IP address.

The description shows up in the Trusted Proxies block alongside the IP address; this makes managing multiple trusted blocks much easier.

Removing an IP address or CIDR range

If you need to remove or edit a trusted proxy entry, you'll need to remove the invalid data (and in the case of editing, add a fresh entry using the steps above). To do so, select the data to remove and click "Remove Selected."

You select the data by single clicking on the IP address you want to remove. To remove multiple addresses, you can hold down Control (for Windows) or Command (for Mac) and single clicking on all the proxies you want to remove.

Single Item: