22 KiB
| title | author | description | manager | ms.author | ms.custom | ms.date | ms.prod | ms.technology | ms.topic | uid |
|---|---|---|---|---|---|---|---|---|---|---|
| Configure ASP.NET Core to work with proxy servers and load balancers | guardrex | Learn about configuration for apps hosted behind proxy servers and load balancers, which often obscure important request information. | wpickett | riande | mvc | 03/26/2018 | asp.net-core | aspnet | article | host-and-deploy/proxy-load-balancer |
Configure ASP.NET Core to work with proxy servers and load balancers
By Luke Latham and Chris Ross
In the recommended configuration for ASP.NET Core, the app is hosted using IIS/ASP.NET Core Module, Nginx, or Apache. Proxy servers, load balancers, and other network appliances often obscure information about the request before it reaches the app:
- When HTTPS requests are proxied over HTTP, the original scheme (HTTPS) is lost and must be forwarded in a header.
- Because an app receives a request from the proxy and not its true source on the Internet or corporate network, the originating client IP address must also be forwarded in a header.
This information may be important in request processing, for example in redirects, authentication, link generation, policy evaluation, and client geoloation.
Forwarded headers
By convention, proxies forward information in HTTP headers.
| Header | Description |
|---|---|
| X-Forwarded-For | Holds information about the client that initiated the request and subsequent proxies in a chain of proxies. This parameter may contain IP addresses (and, optionally, port numbers). In a chain of proxy servers, the first parameter indicates the client where the request was first made. Subsequent proxy identifiers follow. The last proxy in the chain isn't in the list of parameters. The last proxy's IP address, and optionally a port number, are available as the remote IP address at the transport layer. |
| X-Forwarded-Proto | The value of the originating scheme (HTTP/HTTPS). The value may also be a list of schemes if the request has traversed multiple proxies. |
| X-Forwarded-Host | The original value of the Host header field. Usually, proxies don't modify the Host header. See Microsoft Security Advisory CVE-2018-0787 for information on an elevation-of-privileges vulnerability that affects systems where the proxy doesn't validate or restict Host headers to known good values. |
The Forwarded Headers Middleware, from the Microsoft.AspNetCore.HttpOverrides package, reads these headers and fills in the associated fields on HttpContext.
The middleware updates:
- HttpContext.Connection.RemoteIpAddress – Set using the
X-Forwarded-Forheader value. Additional settings influence how the middleware setsRemoteIpAddress. For details, see the Forwarded Headers Middleware options. - HttpContext.Request.Scheme – Set using the
X-Forwarded-Protoheader value. - HttpContext.Request.Host – Set using the
X-Forwarded-Hostheader value.
Note that not all network appliances add the X-Forwarded-For and X-Forwarded-Proto headers without additional configuration. Consult your appliance manufacturer's guidance if the proxied requests don't contain these headers when they reach the app.
Forwarded Headers Middleware default settings can be configured. The default settings are:
- There is only one proxy between the app and the source of the requests.
- Only loopback addresses are configured for known proxies and known networks.
IIS/IIS Express and ASP.NET Core Module
Forwarded Headers Middleware is enabled by default by IIS Integration Middleware when the app is run behind IIS and the ASP.NET Core Module. Forwarded Headers Middleware is activated to run first in the middleware pipeline with a restricted configuration specific to the ASP.NET Core Module due to trust concerns with forwarded headers (for example, IP spoofing). The middleware is configured to forward the X-Forwarded-For and X-Forwarded-Proto headers and is restricted to a single localhost proxy. If additional configuration is required, see the Forwarded Headers Middleware options.
Other proxy server and load balancer scenarios
Outside of using IIS Integration Middleware, Forwarded Headers Middleware isn't enabled by default. Forwarded Headers Middleware must be enabled for an app to process forwarded headers with UseForwardedHeaders. After enabling the middleware if no ForwardedHeadersOptions are specified to the middleware, the default ForwardedHeadersOptions.ForwardedHeaders are ForwardedHeaders.None.
Configure the middleware with ForwardedHeadersOptions to forward the X-Forwarded-For and X-Forwarded-Proto headers in Startup.ConfigureServices. Invoke the UseForwardedHeaders method in Startup.Configure before calling other middleware:
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
services.Configure<ForwardedHeadersOptions>(options =>
{
options.ForwardedHeaders =
ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});
}
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
app.UseForwardedHeaders();
if (env.IsDevelopment())
{
app.UseDeveloperExceptionPage();
}
else
{
app.UseExceptionHandler("/Home/Error");
}
app.UseStaticFiles();
// In ASP.NET Core 1.x, replace the following line with: app.UseIdentity();
app.UseAuthentication();
app.UseMvc();
}
[!NOTE] If no ForwardedHeadersOptions are specified in
Startup.ConfigureServicesor directly to the extension method with UseForwardedHeaders(IApplicationBuilder, ForwardedHeadersOptions), the default headers to forward are ForwardedHeaders.None. The ForwardedHeadersOptions.ForwardedHeaders property must be configured with the headers to forward.
Forwarded Headers Middleware options
ForwardedHeadersOptions control the behavior of the Forwarded Headers Middleware:
services.Configure<ForwardedHeadersOptions>(options =>
{
options.ForwardLimit = 2;
options.KnownProxies.Add(IPAddress.Parse("127.0.10.1"));
options.ForwardedForHeaderName = "X-Forwarded-For-Custom-Header-Name";
});
::: moniker range="<= aspnetcore-2.0"
| Option | Description |
|---|---|
| ForwardedForHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedForHeaderName. The default is X-Forwarded-For. |
| ForwardedHeaders | Identifies which forwarders should be processed. See the ForwardedHeaders Enum for the list of fields that apply. Typical values assigned to this property are ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto.The default value is ForwardedHeaders.None. |
| ForwardedHostHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedHostHeaderName. The default is X-Forwarded-Host. |
| ForwardedProtoHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedProtoHeaderName. The default is X-Forwarded-Proto. |
| ForwardLimit | Limits the number of entries in the headers that are processed. Set to null to disable the limit, but this should only be done if KnownProxies or KnownNetworks are configured.The default is 1. |
| KnownNetworks | Address ranges of known proxies to accept forwarded headers from. Provide IP ranges using Classless Interdomain Routing (CIDR) notation. The default is an IList<IPNetwork> containing a single entry for IPAddress.Loopback. |
| KnownProxies | Addresses of known proxies to accept forwarded headers from. Use KnownProxies to specify exact IP address matches.The default is an IList<IPAddress> containing a single entry for IPAddress.IPv6Loopback. |
| OriginalForHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalForHeaderName. The default is X-Original-For. |
| OriginalHostHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalHostHeaderName. The default is X-Original-Host. |
| OriginalProtoHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalProtoHeaderName. The default is X-Original-Proto. |
| RequireHeaderSymmetry | Require the number of header values to be in sync between the ForwardedHeadersOptions.ForwardedHeaders being processed. The default in ASP.NET Core 1.x is true. The default in ASP.NET Core 2.0 or later is false. |
| ::: moniker-end | |
| ::: moniker range=">= aspnetcore-2.1" | |
| Option | Description |
| ------ | ----------- |
| AllowedHosts | Restricts hosts by the X-Forwarded-Host header to the values provided.
|
| ForwardedForHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedForHeaderName. The default is X-Forwarded-For. |
| ForwardedHeaders | Identifies which forwarders should be processed. See the ForwardedHeaders Enum for the list of fields that apply. Typical values assigned to this property are ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto.The default value is ForwardedHeaders.None. |
| ForwardedHostHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedHostHeaderName. The default is X-Forwarded-Host. |
| ForwardedProtoHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedProtoHeaderName. The default is X-Forwarded-Proto. |
| ForwardLimit | Limits the number of entries in the headers that are processed. Set to null to disable the limit, but this should only be done if KnownProxies or KnownNetworks are configured.The default is 1. |
| KnownNetworks | Address ranges of known proxies to accept forwarded headers from. Provide IP ranges using Classless Interdomain Routing (CIDR) notation. The default is an IList<IPNetwork> containing a single entry for IPAddress.Loopback. |
| KnownProxies | Addresses of known proxies to accept forwarded headers from. Use KnownProxies to specify exact IP address matches.The default is an IList<IPAddress> containing a single entry for IPAddress.IPv6Loopback. |
| OriginalForHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalForHeaderName. The default is X-Original-For. |
| OriginalHostHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalHostHeaderName. The default is X-Original-Host. |
| OriginalProtoHeaderName | Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalProtoHeaderName. The default is X-Original-Proto. |
| RequireHeaderSymmetry | Require the number of header values to be in sync between the ForwardedHeadersOptions.ForwardedHeaders being processed. The default in ASP.NET Core 1.x is true. The default in ASP.NET Core 2.0 or later is false. |
| ::: moniker-end |
Scenarios and use cases
When it isn't possible to add forwarded headers and all requests are secure
In some cases, it might not be possible to add forwarded headers to the requests proxied to the app. If the proxy is enforcing that all public external requests are HTTPS, the scheme can be manually set in Startup.Configure before using any type of middleware:
app.Use((context, next) =>
{
context.Request.Scheme = "https";
return next();
});
This code can be disabled with an environment variable or other configuration setting in a development or staging environment.
Deal with path base and proxies that change the request path
Some proxies pass the path intact but with an app base path that should be removed so that routing works properly. UsePathBaseExtensions.UsePathBase middleware splits the path into HttpRequest.Path and the app base path into HttpRequest.PathBase.
If /foo is the app base path for a proxy path passed as /foo/api/1, the middleware sets Request.PathBase to /foo and Request.Path to /api/1 with the following command:
app.UsePathBase("/foo");
The original path and path base are reapplied when the middleware is called again in reverse. For more information on middleware order processing, see Middleware.
If the proxy trims the path (for example, forwarding /foo/api/1 to /api/1), fix redirects and links by setting the request's PathBase property:
app.Use((context, next) =>
{
context.Request.PathBase = new PathString("/foo");
return next();
});
If the proxy is adding path data, discard part of the path to fix redirects and links by using StartsWithSegments(PathString, PathString) and assigning to the Path property:
app.Use((context, next) =>
{
if (context.Request.Path.StartsWithSegments("/foo", out var remainder))
{
context.Request.Path = remainder;
}
return next();
});
Troubleshoot
When headers aren't forwarded as expected, enable logging. If the logs don't provide sufficient information to troubleshoot the problem, enumerate the request headers received by the server. The headers can be written to an app response using inline middleware:
public void Configure(IApplicationBuilder app, ILoggerFactory loggerfactory)
{
app.Run(async (context) =>
{
context.Response.ContentType = "text/plain";
// Request method, scheme, and path
await context.Response.WriteAsync(
$"Request Method: {context.Request.Method}{Environment.NewLine}");
await context.Response.WriteAsync(
$"Request Scheme: {context.Request.Scheme}{Environment.NewLine}");
await context.Response.WriteAsync(
$"Request Path: {context.Request.Path}{Environment.NewLine}");
// Headers
await context.Response.WriteAsync($"Request Headers:{Environment.NewLine}");
foreach (var header in context.Request.Headers)
{
await context.Response.WriteAsync($"{header.Key}: " +
$"{header.Value}{Environment.NewLine}");
}
await context.Response.WriteAsync(Environment.NewLine);
// Connection: RemoteIp
await context.Response.WriteAsync(
$"Request RemoteIp: {context.Connection.RemoteIpAddress}");
}
}
Ensure that the X-Forwarded-* headers are received by the server with the expected values. If there are multiple values in a given header, note Forwarded Headers Middleware processes headers in reverse order from right to left.
The request's original remote IP must match an entry in the KnownProxies or KnownNetworks lists before X-Forwarded-For is processed. This limits header spoofing by not accepting forwarders from untrusted proxies.