[Breaking change]: Forwarded Headers Middleware Now Ignores X-Forwarded-* Headers from Unknown Proxies

[BrennanConroy]

Description

Starting in ASP.NET Core 8.0.17 and 9.0.6, the Forwarded Headers Middleware will ignore all X-Forwarded-* headers from proxies that are not explicitly configured as trusted.

Version

.NET 8

Previous behavior

Previously, the middleware, when not configured to use X-Forwarded-For, would process X-Forwarded-Prefix, X-Forwarded-Proto, and X-Forwarded-Host headers from any source, potentially allowing malicious or misconfigured proxies/clients to spoof these headers and affect your application's understanding of client information.

New behavior

With this change, only headers sent by known, trusted proxies (as configured via ForwardedHeadersOptions.KnownProxies and ForwardedHeadersOptions.KnownNetworks) will be processed. Headers from unknown sources will be ignored.

This is a breaking change: If your deployment relied on forwarded headers from proxies not configured in your application's trusted proxy list, those headers will no longer be honored.

This can cause behavior like infinite redirects if you're using the Https redirection middleware and using TLS termination in your proxy. Or authentication to fail if using TLS termination and expecting an https request.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
• Behavioral change: Existing binaries may behave differently at run time.

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 KnownProxies or KnownNetworks in your ForwardedHeadersOptions configuration.

  app.UseForwardedHeaders(new ForwardedHeadersOptions
  {
      KnownProxies = { IPAddress.Parse("YOUR_PROXY_IP") }
  });

  Or, for a network:

  app.UseForwardedHeaders(new ForwardedHeadersOptions
  {
      KnownNetworks = { new IPNetwork(IPAddress.Parse("YOUR_NETWORK_IP"), PREFIX_LENGTH) }
  });

• If you wish to enable previous behavior:
  You may need to relax your configuration, but this is not recommended due to security risks. You can do this by clearing the KnownNetworks and KnownProxies lists in 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 targeting .NET 9.0 or less, you can set the Microsoft.AspNetCore.HttpOverrides.IgnoreUnknownProxiesWithoutFor 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 IP(s) can change over the lifetime of the app and ASPNETCORE_FORWARDEDHEADERS_ENABLED is sometimes used to make forwarded headers work.

References

• Forwarded Headers Middleware documentation

Affected APIs

UseForwardedHeaders();