Incorrect Drupal reverse proxy settings can make every visitor appear to share the proxy's IP address—or let visitors supply a false one. Because IP-based access rules use that detected client address, a configuration error can block legitimate users, bypass restrictions, or distort rate limits. A reverse proxy sits between visitors and Drupal, forwarding requests from a load balancer, CDN, or web application firewall. Drupal must trust the correct proxy addresses and forwarded headers to recover the original client IP safely.
Table of Contents
- How Drupal determines the client IP
- How incorrect addresses change access decisions
- What the settings must establish
- Verify the complete request path
- Test both failure directions
How Drupal determines the client IP
Without reverse proxy handling, Drupal normally sees the network address that connected directly to the web server. When a proxy handles incoming traffic, that address belongs to the proxy rather than the visitor. Proxies can pass the visitor's address in a header such as `X-Forwarded-For`.
Drupal relies on Symfony's trusted proxy handling to interpret that header. It should do so only when the immediate request came from a configured, trusted proxy. A forwarded address can pass through several proxies. Correct processing separates trusted proxy hops from the remaining client address instead of assuming the first or last value is always the visitor.
How incorrect addresses change access decisions
If Drupal does not recognize a legitimate proxy, it may treat the proxy's address as every visitor's address. One IP ban could then affect the entire audience routed through that proxy. IP-based throttling can also group unrelated visitors together.
An overly broad trust configuration creates the opposite risk. If attackers can reach the origin directly, they may send their own forwarding headers and influence the address Drupal records. These errors can affect features that depend on the detected client IP, including: A rule can be technically correct yet produce the wrong result because it received the wrong IP.
- Core IP address bans
- Flood-control and login-throttling logic
- Contributed modules with IP allowlists or denylists
- Custom access checks based on address or network range
- Security logs and investigations that use Drupal's client address
What the settings must establish
In modern Drupal versions, reverse proxy configuration belongs in `settings.php`. The exact options depend on the installed Drupal release, but the configuration generally needs to establish three facts: A typical configuration uses settings such as `reverse_proxy`, `reverse_proxy_addresses`, and `reverse_proxy_trusted_headers`.
Administrators should consult the example settings file shipped with their exact Drupal version before copying syntax or header constants. Do not add a visitor-facing CDN's entire possible address space from memory. Use the provider's maintained ranges, account for internal load balancers, and update the configuration when the request path changes.
- Drupal is operating behind a reverse proxy.
- Only specific proxy addresses or controlled network ranges are trusted.
- Only the forwarding headers actually set and sanitized by the infrastructure are trusted.
Verify the complete request path
Start by mapping every hop between the visitor and Drupal. A request might pass through a CDN, an external load balancer, an ingress controller, and an internal proxy before reaching the web server.
Check each component in order: Compare Drupal's detected address with the proxy and web server logs for the same request. Expected differences can occur when IPv4, IPv6, carrier-grade NAT, or privacy relays are involved, but Drupal should not consistently report the proxy address.
- Identify which hop creates or replaces the client-IP header.
- Confirm whether later proxies append to that header or overwrite it.
- Record the source addresses that can connect directly to Drupal.
- Prevent public traffic from bypassing the trusted proxy layer.
- Configure Drupal to trust only the required proxies and headers.
Test both failure directions
A useful test covers both under-trusting and over-trusting. First, confirm that two visitors using different networks do not appear as the same proxy address. Then send a request with a manually supplied `X-Forwarded-For` header through every permitted route.
The submitted header should not override the real address unless a trusted proxy deliberately sanitizes and reconstructs it. If the origin accepts public connections, test that route separately; Drupal must not trust forwarded headers arriving directly from an untrusted client. After changing the settings, review active bans, flood-control records, and custom allowlists. Earlier entries may contain proxy addresses or spoofed values, so correcting detection does not automatically repair decisions based on old data.
