Client IP addresses
Look up your visitor's own IP address when your app runs behind nginx, a load balancer or a CDN, without trusting headers a visitor can forge.
A lookup is only as accurate as the address you give it. This page explains how a proxy hides your visitor's address, how to configure your framework to recover it safely, and how to check the result.
When your app runs behind a proxy, such as nginx, a load balancer or a CDN, the connection your app receives comes from the proxy, not from the visitor. Unless your framework knows which proxies to trust, it reports the proxy's address for every request.
The problem is hard to spot. Every visitor appears to come from your own infrastructure, so VPN visitors pass undetected. If your proxy runs on a hosting network, a rule that blocks hosting traffic blocks everyone.
Trust your own proxies by address
Proxies pass the original client address in a header, usually X-Forwarded-For. Each framework has a setting that tells it which proxies to trust and reads the client address from the header they add:
| Framework | Setting |
|---|---|
| Express | app.set('trust proxy', 'loopback'), or your load balancer's subnet |
| Django | The package's ip_selector, such as header_ip_selector("CF-Connecting-IP"); Django reads no forwarded header itself |
| Laravel | $middleware->trustProxies(at: [...]) in bootstrap/app.php |
| Rails | config.action_dispatch.trusted_proxies |
| Spring Boot | server.forward-headers-strategy=native |
| ASP.NET Core | ForwardedHeadersOptions.KnownProxies |
Each framework package documents its own option for choosing the address.
Count proxies from the right
When requests pass through more than one proxy you control, such as a CDN in front of a load balancer, each proxy appends the address it received from to X-Forwarded-For. The last entries were written by your own proxies, so count entries from the right: with one proxy of your own, the client is the last entry; with two, the second to last.
The framework packages can do this for you. In Express, xffIpSelector({ depth: 1 }) returns the address your nearest proxy saw:
import { vpndetection, xffIpSelector } from 'vpndetection-express';
app.use(vpndetection({
apiKey: process.env.VPNDETECTION_API_KEY,
ipSelector: xffIpSelector({ depth: 1 }),
}));Use your CDN's client header
Many CDNs put the client address in a header of their own:
| CDN | Header |
|---|---|
| Cloudflare | CF-Connecting-IP |
| Akamai | True-Client-IP |
| Fastly | Fastly-Client-IP |
Accept the header only from your CDN's own addresses. Otherwise anyone who reaches your origin directly can set it.
Check your setup
Make a request to your app from your own browser and log the address it passes to the lookup. Then open api.vpndetection.io/myip in the same browser, which shows your public address. The two should match. A private address such as 10.0.0.5 or 127.0.0.1 is expected on your own machine and is a sign of a missing proxy setting anywhere else. The framework packages answer private addresses locally, without a lookup, and log a warning.
Then check that a forged header doesn't fool your app. Send a request with your own X-Forwarded-For value, and confirm that the lookup still uses your real address:
curl -H "X-Forwarded-For: 1.1.1.1" https://your-app.example/If your logs show 1.1.1.1, your app trusts a header any visitor can write. Name your proxies, or count entries from the right, as described above.
Next steps
With the right address in every lookup, protect a web app or review the go-live checklist.