-
Notifications
You must be signed in to change notification settings - Fork 6k
Document .NET 8 breaking change: Forwarded Headers Middleware ignores X-Forwarded-* headers from unknown proxies #47985
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
71 changes: 71 additions & 0 deletions
71
docs/core/compatibility/aspnet-core/8.0/forwarded-headers-unknown-proxies.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| --- | ||
| title: "Breaking change: Forwarded Headers Middleware ignores X-Forwarded-* headers from unknown proxies" | ||
| 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. | ||
| ms.date: 08/15/2025 | ||
| --- | ||
| # Forwarded Headers Middleware ignores X-Forwarded-* headers from unknown proxies | ||
|
|
||
| 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. | ||
|
|
||
| ## Version introduced | ||
|
|
||
| ASP.NET Core 8.0.17 | ||
| ASP.NET Core 9.0.6 | ||
|
|
||
| ## Previous behavior | ||
|
|
||
| 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. | ||
|
|
||
| ## New behavior | ||
|
|
||
| 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. | ||
|
|
||
| > [!NOTE] | ||
| > If your deployment relied on forwarded headers from proxies not configured in your application's trusted proxy list, those headers are no longer honored. | ||
|
|
||
| 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. | ||
|
|
||
| ## Type of breaking change | ||
|
|
||
| This change is a [behavioral change](../../categories.md#behavioral-change). | ||
|
|
||
| ## Reason for change | ||
|
|
||
| The change was made for security hardening, as the proxy and IP lists weren't being applied in all cases. | ||
|
|
||
| ## Recommended action | ||
|
|
||
| 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. | ||
|
|
||
| ```csharp | ||
| app.UseForwardedHeaders(new ForwardedHeadersOptions | ||
| { | ||
| KnownProxies = { IPAddress.Parse("YOUR_PROXY_IP") } | ||
| }); | ||
| ``` | ||
|
|
||
| Or, for a network: | ||
|
|
||
| ```csharp | ||
| app.UseForwardedHeaders(new ForwardedHeadersOptions | ||
| { | ||
| KnownNetworks = { new IPNetwork(IPAddress.Parse("YOUR_NETWORK_IP"), PREFIX_LENGTH) } | ||
| }); | ||
| ``` | ||
|
|
||
| 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. | ||
|
|
||
| You can also set the `ASPNETCORE_FORWARDEDHEADERS_ENABLED` environment variable to `true`, which clears the lists and enables `ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto`. | ||
|
|
||
| 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. | ||
|
|
||
| > [!NOTE] | ||
| > 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. | ||
|
|
||
| ## Affected APIs | ||
|
|
||
| - <xref:Microsoft.AspNetCore.Builder.ForwardedHeadersExtensions.UseForwardedHeaders*?displayProperty=fullName> | ||
|
|
||
| ## See also | ||
|
|
||
| - [Configure ASP.NET Core to work with proxy servers and load balancers](/aspnet/core/host-and-deploy/proxy-load-balancer) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.