|
| 1 | +--- |
| 2 | +title: "Breaking change: Forwarded Headers Middleware ignores X-Forwarded-* headers from unknown proxies" |
| 3 | +description: Learn about the breaking change in ASP.NET Core where Forwarded Headers Middleware now ignores headers from proxies that aren't explicitly configured as trusted. |
| 4 | +ms.date: 08/15/2025 |
| 5 | +--- |
| 6 | +# Forwarded Headers Middleware ignores X-Forwarded-* headers from unknown proxies |
| 7 | + |
| 8 | +Starting in ASP.NET Core 8.0.17 and 9.0.6, the Forwarded Headers Middleware ignores all `X-Forwarded-*` headers from proxies that aren't explicitly configured as trusted. This change was made for security hardening, as the proxy and IP lists weren't being applied in all cases. |
| 9 | + |
| 10 | +## Version introduced |
| 11 | + |
| 12 | +ASP.NET Core 8.0.17 |
| 13 | +ASP.NET Core 9.0.6 |
| 14 | + |
| 15 | +## Previous behavior |
| 16 | + |
| 17 | +Previously, the middleware, when not configured to use `X-Forwarded-For`, processed `X-Forwarded-Prefix`, `X-Forwarded-Proto`, and `X-Forwarded-Host` headers from any source. That behavior potentially allowed malicious or misconfigured proxies/clients to spoof these headers and affect an application's understanding of client information. |
| 18 | + |
| 19 | +## New behavior |
| 20 | + |
| 21 | +Starting in .NET 8 and .NET 9 servicing releases, only headers sent by known, trusted proxies (as configured via <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownProxies?displayProperty=nameWithType> and <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownNetworks?displayProperty=nameWithType>) are processed. Headers from unknown sources are ignored. |
| 22 | + |
| 23 | +> [!NOTE] |
| 24 | +> If your deployment relied on forwarded headers from proxies not configured in your application's trusted proxy list, those headers are no longer honored. |
| 25 | +
|
| 26 | +This change can cause behavior like infinite redirects if you're using the HTTPS redirection middleware and using TLS termination in your proxy. It can also cause authentication to fail if you're using TLS termination and expecting an HTTPS request. |
| 27 | + |
| 28 | +## Type of breaking change |
| 29 | + |
| 30 | +This change is a [behavioral change](../../categories.md#behavioral-change). |
| 31 | + |
| 32 | +## Reason for change |
| 33 | + |
| 34 | +The change was made for security hardening, as the proxy and IP lists weren't being applied in all cases. |
| 35 | + |
| 36 | +## Recommended action |
| 37 | + |
| 38 | +Review your deployment topology. Ensure that all legitimate proxy servers in front of your app are properly added to <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownProxies> or <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions.KnownNetworks> in your <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions> configuration. |
| 39 | + |
| 40 | +```csharp |
| 41 | +app.UseForwardedHeaders(new ForwardedHeadersOptions |
| 42 | +{ |
| 43 | + KnownProxies = { IPAddress.Parse("YOUR_PROXY_IP") } |
| 44 | +}); |
| 45 | +``` |
| 46 | + |
| 47 | +Or, for a network: |
| 48 | + |
| 49 | +```csharp |
| 50 | +app.UseForwardedHeaders(new ForwardedHeadersOptions |
| 51 | +{ |
| 52 | + KnownNetworks = { new IPNetwork(IPAddress.Parse("YOUR_NETWORK_IP"), PREFIX_LENGTH) } |
| 53 | +}); |
| 54 | +``` |
| 55 | + |
| 56 | +If you wish to enable the previous behavior, which isn't recommended due to security risks, you can do so by clearing the `KnownNetworks` and `KnownProxies` lists in <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersOptions> to allow any proxy or network to forward these headers. |
| 57 | + |
| 58 | +You can also set the `ASPNETCORE_FORWARDEDHEADERS_ENABLED` environment variable to `true`, which clears the lists and enables `ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto`. |
| 59 | + |
| 60 | +For applications that target .NET 9 or earlier, you can set the `Microsoft.AspNetCore.HttpOverrides.IgnoreUnknownProxiesWithoutFor` [AppContext](/dotnet/fundamentals/runtime-libraries/system-appcontext) switch to `"true"` or `1` to get back to the previous behavior. Alternatively, set the `MICROSOFT_ASPNETCORE_HTTPOVERRIDES_IGNORE_UNKNOWN_PROXIES_WITHOUT_FOR` environment variable. |
| 61 | + |
| 62 | +> [!NOTE] |
| 63 | +> In cloud environments, the proxy IPs can change over the lifetime of the app, and `ASPNETCORE_FORWARDEDHEADERS_ENABLED` is sometimes used to make forwarded headers work. |
| 64 | +
|
| 65 | +## Affected APIs |
| 66 | + |
| 67 | +- <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersExtensions.UseForwardedHeaders*?displayProperty=fullName> |
| 68 | + |
| 69 | +## See also |
| 70 | + |
| 71 | +- [Configure ASP.NET Core to work with proxy servers and load balancers](/aspnet/core/host-and-deploy/proxy-load-balancer) |
0 commit comments