Limits on Trusting Proxy Headers in CakePHP 4.x/5.x

Resolution

To ensure Request::getClientIp() and Request::is('ssl') return accurate values behind a reverse proxy (like AWS ALB or Nginx), you must enable trustProxy, define the specific trustedHeaders bitmask, and restrict trustedProxies to the known IP ranges of your load balancer.

Recommended Configuration

In your configuration (typically config/app.php or via the ServerRequestFactory), use the following logic:

'trustProxy' => true,
'trustedProxies' => ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'], // Replace with your VPC/Subnet CIDRs
'trustedHeaders' => Request::HEADER_X_FORWARDED_FOR | Request::HEADER_X_FORWARDED_PROTO,

Detailed Explanation

CakePHP ignores X-Forwarded-* headers by default. When trustProxy is enabled, the framework only honors these headers if the request originates from an IP address listed in trustedProxies. If the request comes from an untrusted IP, the headers are discarded to prevent spoofing.

• SSL Detection: You must include HEADER_X_FORWARDED_PROTO. Because ALBs typically terminate TLS and forward requests to the app server via HTTP, is('ssl') will return false unless this header is trusted and parsed.
• IP Detection: Including HEADER_X_FORWARDED_FOR allows getClientIp() to extract the original client IP from the proxy chain.
• Host Detection: Only add HEADER_X_FORWARDED_HOST if your application logic specifically relies on the proxied host header. Avoid this unless necessary to reduce the surface area for host-header injection attacks.

Security and Scope

Trusting all X-Forwarded-For values without restricting trustedProxies is a security risk; any client can send a fake header to impersonate an IP address.

Because AWS ALB node IPs are dynamic and change as the balancer scales, do not hardcode individual IP addresses. Instead, scope trustedProxies to your VPC or private subnet CIDR ranges. This ensures that only traffic coming from your internal network infrastructure is trusted.

Version Note

CakePHP 5.x does not automatically detect cloud provider headers. Manual configuration of trustedProxies and trustedHeaders remains required to maintain security and accuracy.

Verification Steps

1. Verify Client IP: Log $this->request->getClientIp(). It should match the external client IP, not the ALB's internal IP.
2. Verify SSL: Check $this->request->is('ssl'). It should return true when accessed via HTTPS through the ALB.
3. Test Spoofing: Send a request directly to the app server (bypassing the ALB) with a manual X-Forwarded-For header. The app should ignore this header and return the actual direct connection IP.

Diagnostic Question: Are there multiple proxy hops (e.g., Cloudflare $\rightarrow$ ALB $\rightarrow$ Nginx $\rightarrow$ App)? If so, trustedProxies must include the IP ranges of every hop that directly contacts your application.