skip to content

In ASP.NET Core, what exactly does setting ASPNETCORE_FORWARDEDHEADERS_ENABLED=true configure, and when is it unsafe to use?

level: middleimportance: should knowfreq 28%

answer

  1. configuration key ForwardedHeaders_Enabled
  2. an IStartupFilter adds the middleware
  3. XForwardedFor plus XForwardedProto
  4. both trust lists cleared
  5. ForwardLimit stays 1

basics

~20 s

It adds UseForwardedHeaders at the very start of the pipeline, processes X-Forwarded-For and X-Forwarded-Proto, and clears KnownProxies and KnownIPNetworks so every sender is trusted. That is unsafe whenever clients can reach Kestrel without passing the proxy.

solid answer

~40 s

The variable maps to the configuration key `ForwardedHeaders_Enabled`. When it is `true`, the web host defaults used by `WebApplication.CreateBuilder` do two things: an `IStartupFilter` calls `UseForwardedHeaders()` ahead of your own middleware, and an options setup sets `ForwardedHeaders = XForwardedFor | XForwardedProto` and **clears** `KnownProxies` and `KnownIPNetworks`. `ForwardLimit` stays at its default of 1, so the rightmost entry is taken from whoever connected. It exists for platforms where the proxy's address is not known in advance and only the proxy can reach the app. If Kestrel is also reachable directly, or the proxy forwards a client's own headers, any client can set its IP and scheme. You can still narrow it: your own `Configure<ForwardedHeadersOptions>` runs after the preset and can add proxies back.

code

yaml · 11 lines
yaml
services:
  liftpass-shop:
    image: liftpass-shop:latest
    environment:
      ASPNETCORE_FORWARDEDHEADERS_ENABLED: "true"
    expose:
      - "8080"   # reachable only on the internal network, from the proxy
  proxy:
    image: nginx:stable
    ports:
      - "443:443"

go deeper

for a junior

Recall that one environment variable can switch on forwarded headers handling without code changes in Program.cs.

for a middle

Explain exactly what the preset sets: the two flags, the cleared trust lists, the unchanged ForwardLimit and the middleware inserted first.

for a senior

Judge whether the network really isolates Kestrel before using the preset, and narrow it with a later options configuration when it does not.

for a principal

Set a platform rule for where trust is configured, in code or in deployment variables, so a reachable container never ships with an open preset.

## Where the switch lives ASP.NET Core's web host defaults, the ones `WebApplication.CreateBuilder`, `WebApplication.CreateSlimBuilder` and `ConfigureWebHostDefaults` apply, register two internal services that both read the configuration key **`ForwardedHeaders_Enabled`**: - a startup filter (`IStartupFilter`) that, when the value is `true`, calls `app.UseForwardedHeaders()` **before** the rest of your pipeline; - an `IConfigureOptions<ForwardedHeadersOptions>` that, when the value is `true`, configures the middleware. `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` is simply the environment-variable spelling of that key (the `DOTNET_` prefix works too, and so would the key in `appsettings.json`). `WebApplication.CreateEmptyBuilder` registers neither, so the switch does nothing there. ## What the preset sets | Setting | Value under the preset | Default without it | |---|---|---| | Middleware in pipeline | added first, by the startup filter | only if you call `UseForwardedHeaders` | | `ForwardedHeaders` | `XForwardedFor \| XForwardedProto` | `None` | | `KnownProxies` | **cleared** | `::1` | | `KnownIPNetworks` | **cleared** | `127.0.0.0/8` | | `ForwardLimit` | `1` (unchanged) | `1` | Clearing both lists disables the trust check entirely. The comment in the source states the intent: forwarders are being enabled by explicit configuration, so the loopback-only restriction is removed. ## Why it exists On many hosting platforms and container orchestrators the proxy's address is not known when the image is built and may change on every deployment. Writing `KnownProxies` into code would break on the next rollout. The preset gives a one-line way to restore the client IP and `https` scheme when **the platform guarantees that only its proxy can reach the app**. ## When it is unsafe 1. **Kestrel is reachable directly.** A container with a published port, a VM with a public IP, or a pod reachable from other pods: any caller can send `X-Forwarded-For: 192.0.2.66` and `X-Forwarded-Proto: https`, and with no trust list the middleware applies them. Logs, per-client limits and IP allow-lists become attacker-controlled, and `Request.IsHttps` becomes `true` on plain HTTP. 2. **The proxy passes client headers through.** With `ForwardLimit = 1` the rightmost entry is used. That is the proxy's own observation only if the proxy appends; a proxy that forwards the client's header unmodified hands the client the choice. 3. **It is left on in an edge deployment.** The ASP.NET Core security guidance warns to check Dockerfiles, orchestrator manifests and platform settings for the variable when Kestrel faces the internet. ## Narrowing it Options configuration runs in registration order, and the host defaults register their setup before your services. So a later `builder.Services.Configure<ForwardedHeadersOptions>(...)` still runs **after** the preset and can: - add the proxy subnet back to `KnownIPNetworks`, restoring the trust check; - add `XForwardedHost` with `AllowedHosts`, or `XForwardedPrefix`; - raise `ForwardLimit` for a multi-proxy chain. If you need that much control, it is usually clearer to drop the variable and call `UseForwardedHeaders` with explicit options in `Program.cs`, where reviewers can see the trust decision. ## Quick checks - Is the variable set? Inspect the container image, Compose or Kubernetes manifests and platform app settings. - Can anything other than the proxy reach the port? If yes, do not use the preset unmodified. - Send a request with a forged `X-Forwarded-For` straight to Kestrel and log `RemoteIpAddress`; if the forged value appears, the app trusts everyone.

  • Does ASPNETCORE_FORWARDEDHEADERS_ENABLED also process X-Forwarded-Host?
    No. The preset sets only `ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto`. If the proxy rewrites the Host header and sends the original in `X-Forwarded-Host`, add `XForwardedHost` yourself in a `Configure<ForwardedHeadersOptions>` call, and restrict `AllowedHosts` because the trust lists are empty.
  • The variable is set but RemoteIpAddress is still the proxy. What would you check first?
    That the builder actually applies the web host defaults: `WebApplication.CreateEmptyBuilder` does not register the startup filter. Then that the proxy really sends `X-Forwarded-For`, and that no later configuration reset `ForwardedHeaders` to `None` or re-added a trust list that excludes the proxy's real address.

  • The variable turns on ForwardedHeaders.All, including X-Forwarded-Host.
  • It keeps the loopback-only KnownProxies, so it is always safe.
  • It sets ForwardLimit to null so the whole chain is read.
  • You must also call app.UseForwardedHeaders() or the variable has no effect.
  • Setting ASPNETCORE_HTTP_PORTS is what makes the app honour forwarded headers in containers.