Skip to content
VPNDetection

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:

FrameworkSetting
Expressapp.set('trust proxy', 'loopback'), or your load balancer's subnet
DjangoThe 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
Railsconfig.action_dispatch.trusted_proxies
Spring Bootserver.forward-headers-strategy=native
ASP.NET CoreForwardedHeadersOptions.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:

js
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:

CDNHeader
CloudflareCF-Connecting-IP
AkamaiTrue-Client-IP
FastlyFastly-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:

bash
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.