Forward client IP through a proxy
Behind a proxy the TCP peer is the proxy, so the app sees one IP for all users. The real client address arrives in a header — and that header is client-controllable unless you strip and re-add it at the edge.
Procedure
- Confirm what your reverse proxy sets. Nginx with
real_ip:set_real_ip_from 10.0.0.0/8; # only your LB range real_ip_header X-Forwarded-For; real_ip_recursive on; - Strip inbound trust headers at the edge so a client cannot smuggle a fake IP:
Appending (proxy_set_header X-Forwarded-For $remote_addr; # overwrite, do not append proxy_set_header X-Real-IP $remote_addr;$proxy_add_x_forwarded_for) preserves client-supplied values — only do that when every upstream hop re-strips. - In the app, enable proxy trust for exactly the known hops, not
*:from werkzeug.middleware.proxy_fix import ProxyFix app.wsgi_app = ProxyFix(app.wsgi_app, x_for=1, x_proto=1, x_host=1) # trust ONE hopx_for=1reads the last ingress-appended value, which is the closest trusted proxy's view. - Set the framework's trusted-proxy CIDR list (Django
SECURE_PROXY_SSL_HEADER+USE_X_FORWARDED_HOST, Expressapp.set('trust proxy', '10.0.0.0/8')). - Verify the app now sees the client, not the proxy:
Against a properly-stripping edge, a spoofedcurl -s http://api.example.com/whoami -H 'X-Real-IP: 203.0.113.9'X-Real-IPshould be ignored and the response should show your real source address. - Check the access log format records the resolved client field, not
$remote_addr.
Pitfalls
trust proxy: true/x_for=*trusts any hop, so anyone can spoof IPs and defeat rate limits and geo rules.- Appending to an existing
X-Forwarded-Forlets a client control the leftmost value; count hops from the right. - Two chained proxies without re-stripping leave two entries and the app reads the wrong one.
- Cloudflare/CloudFront add their own header (
CF-Connecting-IP,CloudFront-Viewer-Address); prefer it at the edge, then re-emit a single canonical header. - Rate limiting on the raw socket IP throttles the proxy, not the abuser — everyone shares one bucket.
- IPv6 addresses with ports (
[2001:db8::1]:443) break naive string splitting and produce garbage keys. - Trusting a header for authz decisions ("internal IP = admin") turns spoofing into privilege escalation.
Verification
curl -s https://api.example.com/ip -H 'X-Forwarded-For: 1.2.3.4'
# response must show YOUR real IP, not 1.2.3.4
Pass means injected client headers are ignored and the app logs the true source. Report: "edge rewrites XFF, ProxyFix x_for=1, spoofed XFF rejected; logs now show real client IP."