Trusted Proxy Headers: Preserve Client IPs Without Trusting Spoofed Values

A reverse proxy often connects to an application on behalf of the visitor. Without additional context, the application sees the proxy's address rather than the visitor's. Forwarded headers can preserve useful information such as client address and original scheme, but they are still request data. Trusting an arbitrary header sent from the internet can let a caller influence logs, rate limits, or URL generation.

Draw the complete request path

Record every hop from browser to application: an external edge service if present, the VPS reverse proxy, and the application listener. Identify which hop creates, replaces, or appends each forwarding header. Do not combine instructions for a single local proxy with a multi-proxy deployment without understanding how the chain changes.

Also record whether the application can be reached directly. If it accepts public requests that bypass the trusted proxy, its assumptions about sanitized headers may be false. Bind the upstream to an appropriate local or private interface and enforce the intended access policy at all relevant layers.

Limit trust to the proxies you control

Use the web server and framework's documented trusted-proxy mechanisms. Configure the actual trusted addresses or networks and the expected header format. Never designate every internet address as a trusted proxy merely to make the client-IP field appear populated. If an external provider changes its address ranges, manage that dependency through a maintained process.

Scheme forwarding requires equal care. The application may use the perceived HTTPS state when deciding cookie security, redirects, and absolute links. Trust a forwarded scheme only when the known proxy overwrites or otherwise safely establishes it and untrusted clients cannot supply an accepted alternative path.

Test legitimate and forged requests

In your own staging environment, send a normal request through the intended proxy and confirm that the application records the expected client context. Then send a request containing a deliberately false forwarding header from an untrusted client. The application should continue deriving its trusted context from the approved boundary rather than accepting the caller's claim.

For example, if an IP-based limit treats a fabricated header as a new client, the limiter may be attached to untrusted data. Fix the provenance of the address before tuning the limit. Preserve a minimal test record without logging authentication cookies, API tokens, or full user request bodies.

Review downstream consumers

List every feature that uses client address or scheme: abuse controls, audit trails, secure cookies, URL generation, and administrative allowlists. A proxy change can affect all of them at once. Retest those behaviors after adding a CDN or replacing a reverse proxy. Keep original connection metadata available in appropriately protected operational logs when useful, and avoid presenting an inferred client address as stronger identity than it is.

The nginx real IP module documents trusted address handling. See our Coolify hosting guide for a proxy-based deployment and LayerOne docs for the server's network context.