Setting the environment variable to enable forwarded headers needs to be more prominent

[paulcustance-al]

While trying to get X-Forwarded-Proto header to be respected and after much frustration I noticed that in of the code sample it has

Environment.GetEnvironmentVariable("ASPNETCORE_FORWARDEDHEADERS_ENABLED")

Which led me to realise that I needed to set this environment variable in order to get it to work. Perhaps this information aught to be more prominent?

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: e548cd16-b06c-5802-a1a7-c627167857ae
• Version Independent ID: c48abb08-bea3-dcff-c067-2edf5dc9b3a6
• Content: Configure ASP.NET Core to work with proxy servers and load balancers
• Content Source: aspnetcore/host-and-deploy/proxy-load-balancer.md
• Product: aspnet-core
• Technology: aspnetcore-hostdeploy
• GitHub Login: @Rick-Anderson
• Microsoft Alias: riande

[serpent5]

Just FYI, setting this environment variable isn't required - it's for convenience so that you don't have to add both services.Configure<ForwardedHeadersOptions>(...) and app.UseForwardedHeaders(); with the correct setup: https://github.com/dotnet/aspnetcore/blob/release/3.1/src/DefaultBuilder/src/WebHost.cs#L240-L252.

[Rick-Anderson]

@serpent5 that's great information. Is it worth adding

In the preceding code, setting Environment.GetEnvironmentVariable("ASPNETCORE_FORWARDEDHEADERS_ENABLED") variable isn't required - it's for convenience so that you don't have to add both services.Configure<ForwardedHeadersOptions>(...) and app.UseForwardedHeaders(); with the correct setup: https://github.com/dotnet/aspnetcore/blob/release/3.1/src/DefaultBuilder/src/WebHost.cs#L240-L252.

Let me know if you'd like to add that.

[serpent5]

It looks like things have changed a bit since that section was written. The code sample that the reader is instructed to add is now part of the ConfigureWebDefaults stuff. I think it might be worth adding a note about how ASPNETCORE_FORWARDEDHEADERS_ENABLED is used by ConfigureWebDefaults to add both the configuration and the middleware. The only mention of that setting right now is in the code sample, but it doesn't really show that it has built-in support.

From what I see, if you're using ConfigureWebDefaults, you can just set the env var, without adding the code shown in the sample. Otherwise, you can add the code yourself, but then there's no need to use the ASPNETCORE prefix on the setting name because it's being read by the app's code.

For reference, I found the PR that made the change: #12740. It looks like it was during the transition to 3.x, so it might be worth seeing if @Tratcher can comment on what I've said above.

[Tratcher]

Yup, these could use some updates.

1. ASPNETCORE_FORWARDEDHEADERS_ENABLED is supported by ConfigureWebDefaults starting in 3.0. The sample code should only be shown for older versions.
2. Add a disclaimer: ASPNETCORE_FORWARDEDHEADERS_ENABLED should only be used in deployment scenarios where you're:
   A. Positive you're behind a trusted proxy
   B. AND the deployment environment is unpredictable such that you can't specify KnownProxies or KnownNetworks. A cloud provider is such an environment.
3. Otherwise you should configure ForwardedHeadersOptions as shown above and set KnownProxies/Networks.

[Rick-Anderson]

@serpent5 would you like to PR this when you have time?

[serpent5]

Yeah, it's on my list.

[martincostello]

I just stumbled across this issue while trying to get an ASP.NET Core app using OAuth working when debugging with GitHub Codespaces and getting really confused why the redirect URLs were sending localhost instead of the preview URL for the codespace.

I've written this up on my blog, but maybe adding something about needing to add ForwardedHeaders.XForwardedHost for Codespaces would be useful?

Specifically, with ASPNETCORE_FORWARDEDHEADERS_ENABLED set to true, I also had to add the following to my app:

if (string.Equals(builder.Configuration["CODESPACES"], "true", StringComparison.OrdinalIgnoreCase))
{
    builder.Services.Configure<ForwardedHeadersOptions>(
        options => options.ForwardedHeaders |= ForwardedHeaders.XForwardedHost);
}