How QIIUB determines the client IP

Why the platform needs the real client IP, where it actually lives in each Azure hosting topology, the options for reading it, and the approach QIIUB uses and why it holds up. Reference doc — read this to understand why client-IP handling is configured the way it is.

Created: 2026-07-11 | Last Updated: 2026-07-11

Contents: Why it matters · Glossary · Where the real IP lives · The options · What QIIUB uses & why · Two pitfalls · Rate-limit key · Sources

Why the client IP matters here

QIIUB records the caller's IP in several security-relevant places: session records (RefreshToken.IpAddress, shown on the user's sessions page), magic-link and handoff audit rows, SystemAuditLog, AI request logs, and the anonymous rate-limit bucket. If that value is the address of an infrastructure proxy instead of the real client, every one of those becomes useless (or worse, misleading in an incident). So "what is the real client IP, reliably?" is a real security question, not a cosmetic one.

The subtlety: the answer depends on what sits in front of the app. The same code returns different things on Linux vs Windows App Service vs behind a CDN/Front Door. This doc makes that explicit so the behavior isn't a surprise on a future infra change.

Glossary (plain English)

RemoteIpAddress: The IP of the TCP connection ASP.NET Core actually sees (HttpContext.Connection.RemoteIpAddress). If a proxy sits in front, this is the proxy's IP unless forwarded-headers processing rewrites it. The client cannot forge it — it is the real socket peer.
XFF — X-Forwarded-For: The standard header where a proxy writes the original client IP (a comma-chain, one hop per proxy). If no trusted proxy stripped/set it, a client can send a fake one — so XFF is only trustworthy when a known proxy set it.
X-Azure-ClientIP / X-Azure-SocketIP: Front-Door-specific headers. SocketIP = the TCP peer Front Door accepted (not client-forgeable — the most trustworthy signal). ClientIP = what Front Door believes is the client.
Trusted proxy — KnownNetworks / KnownProxies: The allowlist of proxy IP ranges you trust to have set XFF. ASP.NET Core (since .NET 8.0.17 / 9.0.6) ignores XFF from anything not on this list. Empty list = trust nobody.
ForwardLimit: How many proxy hops to walk back in the XFF chain. 1 = one proxy in front (App Service alone). 2 = two (App Service behind Front Door).
ASPNETCORE_FORWARDEDHEADERS_ENABLED: An env var the Azure Linux .NET base image sets to true, auto-wiring forwarded-headers processing with the trust list cleared and ForwardLimit=1. Convenient, but implicit and easy to lose on an infra change.

Where the real IP lives, per topology

Same app, three ways to host it. In each: what does RemoteIpAddress resolve to, and where is the true client IP?

1 · Linux App Service QIIUB today

The blessed Linux image sets ASPNETCORE_FORWARDEDHEADERS_ENABLED=true, so Kestrel reads the rightmost XFF entry the front-end set. Verified empirically in QA: session rows record the real client IP.

2 · Windows App Service alternative

Different mechanism — IIS/ARR rewrites REMOTE_ADDR before .NET sees the request, and IIS integration auto-enables forwarded headers. A Linux→Windows move keeps the real IP working.

3 · Behind Front Door / CDN needs config

Two proxy hops. With ForwardLimit=1, RemoteIpAddress resolves to Front Door's egress, not the client. Requires ForwardLimit=2 + FD ranges in KnownNetworks, or reading X-Azure-SocketIP.

A CDN/Front Door does not "just work". It provides the client IP (in XFF / X-Azure-SocketIP), but with a one-hop config the app reads the CDN's own IP. Fronting the app is a deliberate config change, never transparent — which is the whole reason to make the trust config explicit rather than implicit.

The options for reading the client IP

Option	What it is	Trade-off
Rely on the platform env-var	Let the Linux image's `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` do it implicitly.	Works today with zero code — but invisible, Linux-only, trust-all, and silently lost on a Windows move or image change. Correctness you can't see in the repo.
Explicit `UseForwardedHeaders` + known networks chosen	Wire the middleware in code; trust only configured proxy ranges (`KnownNetworks`), hop count from config.	The industry standard ("trust only your known edge"). Correct on Linux & Windows; a future CDN is a config change, not code. One visible source of truth for proxy trust.
*Read `X-Azure-` headers directly**	Skip XFF hop-math; read `X-Azure-SocketIP` (Front-Door-authoritative).	Best precision behind Front Door, but Front-Door-specific — doesn't help the no-CDN topology. A later add-on if/when Front Door lands.
Trust-all (clear the lists)	Accept XFF from any peer.	Rejected. If the app is ever reachable without a real proxy in front, a client can forge its IP. Flagged as insecure by the framework since .NET 8.0.17.

What QIIUB uses & why it works

QIIUB wires UseForwardedHeaders explicitly, first in the pipeline, trusting only configured proxy ranges:

ForwardedHeaders = XForwardedFor | XForwardedProto   // not XForwardedHost
ForwardLimit    = 1        // from config; 2 when behind Front Door
KnownNetworks   = [ ... ]  // from config: App Service internal range now; add FD range later
// KnownProxies/KnownNetworks are NEVER cleared (trust-all)

Why this holds up across every topology:

Linux & Windows direct: identical config; the real client IP lands in RemoteIpAddress for audit, sessions, and rate-limiting.
Future CDN / Front Door: a config change — add the FD range to KnownNetworks, set ForwardLimit=2 (or read X-Azure-SocketIP). No code ships at cutover.
Local / tests: no trusted proxy → the middleware is inert → the connection IP is used as-is. Nothing to special-case.
Anti-spoofing: because only known proxy ranges are trusted, a client that sends a fake X-Forwarded-For is ignored — the recorded IP stays honest.

The principle in one line: trust only your known edge, and read the header it sets. Everything else (which header, how many hops) is configuration, kept in one place.

Two pitfalls the config guards against

Empty KnownNetworks is not "safe default" — it's a no-op. Empty = trust nobody = XFF never applied, so if the platform env-var is also off, RemoteIpAddress becomes the internal proxy IP and every audit/session/rate-limit value degrades. The trust list must be populated with the real proxy range, not left empty.

Don't run two forwarded-headers passes. The explicit middleware and the platform env-var must not both be active, or the second pass consumes an attacker-controlled XFF entry. QIIUB pins ASPNETCORE_FORWARDEDHEADERS_ENABLED=false so the explicit, visible config is the only one in effect.

The rate-limit key — and why IP is right here

Once the real IP is trustworthy, it's used to bucket anonymous / pre-auth traffic (login, magic-link, refresh) in the global limiter. A common question: shouldn't a multi-tenant SaaS key rate limits on the tenant instead of IP? For most SaaS, yes — but QIIUB's traffic model is different:

POS sales don't hit rate-limited HTTP endpoints. Terminals work offline and reconcile through Sync/Push (batched). The throttled surface is auth (pre-login) + AI + low-volume back-office web CRUD.
Pre-auth endpoints have no tenant identity yet, so IP (plus email for login) is the correct key regardless.
The "one busy tenant starves another" concern that pushes general SaaS toward tenant-keying doesn't arise, because no high-frequency per-user API path exists.

So the limiter keys on the (now-trustworthy) client IP, and the edge WAF — if a CDN is ever added — stays the coarse volumetric layer on top. App-level and edge-level limiting are complementary layers, not either/or.

Status: the Linux behavior above is verified empirically in QA; the explicit-wiring approach is the decided design (tracked for implementation in issue #702, part of the session-security epic, ADR-0117 §8). This page explains the why; the issue tracks the rollout.

Sources

MS — Configure ASP.NET Core to work with proxy servers and load balancers
MS — Breaking change: forwarded headers ignored from unknown proxies (8.0.17/9.0.6)
MS — Front Door HTTP headers (X-Azure-ClientIP / X-Azure-SocketIP)
MS — Rate limiting middleware
FastEndpoints — Rate Limiting

Related: docs/adr/0117-session-security-architecture.md §8 · docs/security/session-threat-model.md · docs/html/qiiub-session-token-security.html.