Traefik forwarded headers define who may rewrite the client identity
Traefik can read X-Forwarded-* headers and use them to describe the original client, protocol, host, and port. The forwardedHeaders.trustedIPs setting limits that trust to configured IP addresses or CIDRs. The forwardedHeaders.insecure setting always trusts the incoming headers. These options are part of the entry point's network contract, and they directly affect logs, access rules, rate limits, and any application that derives authorization or tenant identity from the forwarded chain.
The security question is simple: can a request reach the relevant entry point without first passing through a proxy whose address is in the trusted list? If the answer is yes, an unauthenticated caller may be able to supply a header value that Traefik accepts. The application may then treat that value as the client address or as evidence about the original scheme.
The proxy chain is the policy
An edge load balancer, a cloud service, and a Kubernetes ingress controller can each add or preserve forwarded headers. Traefik only knows the IP address that connected to its listener and the header values it receives. trustedIPs is therefore a list of peers whose header assertions Traefik is willing to accept. It is not a list of end-user networks, and it should not contain broad ranges merely because they contain one proxy.
Use insecure only in a lab or in a topology where an untrusted client cannot reach the entry point. The setting always trusts the headers, which removes the peer-address check. A public listener with insecure enabled and a backend that uses X-Forwarded-For for access decisions is a header-trust failure waiting to happen.
notAppendXForwardedFor controls whether Traefik appends the immediate client address. Changing it can alter the meaning of the header chain for every downstream service. Treat it as part of the logging and trust model, not a cosmetic option.
Test direct paths as well as the intended path
Identify every address that can reach the Traefik entry point. The normal path might pass through a cloud load balancer, but a rollout may accidentally expose the node port, a service address, or a secondary interface. A request that bypasses the trusted proxy can arrive with attacker-controlled headers and still look valid to Traefik if the configuration trusts all peers.
Check the entry point configuration for trustedIPs, insecure, and notAppendXForwardedFor. Compare those settings with the actual load-balancer addresses in IPv4 and IPv6. Include the proxy health-check source and any disaster-recovery path. If a proxy address changes during failover, the new address must be in the trust policy before traffic moves.
Send controlled requests to a test instance and observe the client address that the backend receives. Test a direct request, a request through the intended proxy, and a request with a forged left-most header. The last test should not change the trusted address when the direct peer is not trusted. Test application behavior that depends on the protocol and host fields as well as the client IP.
Keep application trust narrow
Do not let a downstream service use X-Forwarded-For as proof of authentication. A forwarded address can be useful for coarse network policy, rate limiting, and audit enrichment, but it is not a signed identity. Use a trusted proxy that sets a separate, authenticated identity header and strip that header from external requests. If the backend needs a cryptographic statement, use a signed token or mutual TLS rather than a header chain.
Redact sensitive headers from logs and support bundles. The forwarded headers may disclose internal addresses, hostnames, or proxy topology. Keep the trust configuration in version control, and restrict who can change the entry point configuration. A routing change can silently broaden the trust boundary.
Monitor rejected and unusual forwarded headers at the edge. A sudden stream of direct requests with suspicious X-Forwarded-For values may indicate probing for a bypass. Network policy should make the direct path unreachable even when the header policy is correct.
Traefik's forwarded-header settings are small configuration fields with a large effect. They tell the proxy which peers may speak for the client. Treat that statement as an authentication boundary, test it from every reachable path, and keep the list of trusted peers as narrow as the deployment allows.
Top comments (0)