Trust boundaries for Forwarded and X-Forwarded-For

Core idea

Forwarded and X-Forwarded-For are data, not proof. A client can supply them, so an application should trust only values added by known final proxy hops after untrusted input is removed or normalized.

Start Trust boundaries for Forwarded and X-Forwarded-For with a threat model: what data needs protection, from whom, and on which link. Proxy credentials control access, TLS protects origin traffic, and an IP allowlist narrows the source network. These controls complement one another but do not make an unsafe workflow safe by themselves.

What the primary source establishes

Define trusted reverse-proxy hops and prove that a forged incoming header cannot bypass logging or rate limits.

The primary source, RFC 7239 — Forwarded, RFC 9110 — HTTP Semantics, MDN Forwarded, MDN X-Forwarded-For, OWASP SSRF Prevention, defines the technical baseline but not every client and provider configuration. Read the normative behavior with its version and then verify your implementation. Treat anything beyond the source as a product feature that needs separate confirmation.

Controlled lab

Expose an isolated direct test port beside an edge-only application path. Send forged IPv4, IPv6, unknown, and quoted values. Verify Forwarded normalization, list limits, and unknown-peer handling. The limiter must use the validated address rather than the first text token.

Step-by-step verification

Draw client to edge to application, then define trusted addresses or hop count. Compare a direct forged request, one edge hop, and two trusted hops while retaining both the selected client address and socket peer.

Use a test account and an authorized endpoint. Issue short-lived, least-privilege credentials and define revocation before the run. Verify normal access, rejection with a bad secret, and rejection from an unapproved source. Error messages must remain distinct without echoing credentials.

Inspect application logs, command history, HAR files, and support output. A connection string may leak through a URL, process arguments, terminal history, or screenshots. Rotate temporary credentials and remove sensitive test artifacts after verification.

• Map trusted hops
• Forge an inbound header
• Test IPv4 and IPv6
• Bind limits to the validated address

Evidence to retain

Record socket peer, normalized chain, selected client address, trust-rule version, and limiter decision. Minimize or pseudonymize long-lived address data according to policy.

A security report stores the check ID, time, result, and policy, never a password, cookie, token, secret URL, or reusable browser state. Record that credentials changed rather than storing the old and new values. Evidence should prove the control without becoming another secret store.

Define report columns and time format before the run. A result without context becomes a guess: the address, cache state, and changed condition are unknown. Record controlled failures as well as successes so the check proves that it can distinguish states.

Interpreting the result

Rate limiting, auditing, and geography should share one reviewed parser. Choosing the first or last element without a chain model enables spoofing, while unbounded lists create another input risk.

A correct Forwarded field does not identify a person and may be removed between networks. PROXY protocol and vendor-specific headers need separate handling.

One successful run confirms only one client, route, and moment. Repeat while changing one variable and state the limits. When observation conflicts with documentation, rule out cache, client version, and intermediaries before creating a reproducible support case.

Worked decision process

Build an access register for Trust boundaries for Forwarded and X-Forwarded-For with owner, purpose, expiry, allowed network, and revocation path. Shared credentials prevent selective revocation and useful audit. Issue replacement access, verify one safe request, and then revoke the old secret.

Run negative checks after successful access: old credentials, an unapproved source IP, and an invalid destination. Confirm rejection at the intended stage without echoing a secret. Inspect browser history, process output, CI logs, and support attachments for complete connection strings.

Review active access on a schedule. Match each record to an owner and task, remove orphaned entries, and give exceptions an owner and deadline. The review result is a list of retained, revoked, and time-bounded exceptions rather than a checkbox.

Common mistakes

Disabling certificate validation, sharing one team password, allowing a broad CIDR, and pasting proxy URLs into chat are recurring failures. Restore validation, create scoped credentials, narrow the source range, and verify that old access has actually been revoked.

Stop when errors rise, a source returns a limit, the task would require bypassing protection, or secrets enter logs. Save sanitized diagnostics and correct the cause first. More concurrency or another IP can hide the fault and add load without improving evidence.

Rollout and maintenance criteria

Define the decision boundary before rollout: which observation permits continuation, which requires review, and which stops the workflow. Record acceptable error ratio, maximum wait, and the owner of every exception so a temporary failure cannot silently become permanent configuration.

Review real load, cost, and quality after the first week. Schedule a small control after client, proxy-service, or network changes. Archive outdated instructions with their replacement date and reason so operators do not follow conflicting configurations.

Operational checklist

Turn the successful experiment into a short procedure covering owner, safe configuration, limits, and stop conditions. Every run needs a terminal status. After browser, library, or network changes, run a small control before the main queue.

• Assets and threat are defined
• Test access is isolated
• TLS validation remains on
• Logs were checked for leaks
• Revocation is documented
• Negative cases were tested