From d1501690ce57b2a84b02821834ece94ddebf1311 Mon Sep 17 00:00:00 2001
From: Luke Latham <1622880+guardrex@users.noreply.github.com>
Date: Tue, 29 May 2018 20:45:35 -0500
Subject: [PATCH] Forwarded headers updates for Nginx/Apache topics (#6644)
Updates
---
aspnetcore/host-and-deploy/linux-apache.md | 28 +++++++++++++++----
aspnetcore/host-and-deploy/linux-nginx.md | 8 ++++--
.../host-and-deploy/proxy-load-balancer.md | 12 ++++++--
3 files changed, 39 insertions(+), 9 deletions(-)
diff --git a/aspnetcore/host-and-deploy/linux-apache.md b/aspnetcore/host-and-deploy/linux-apache.md
index 8911c4320d..43346648f1 100644
--- a/aspnetcore/host-and-deploy/linux-apache.md
+++ b/aspnetcore/host-and-deploy/linux-apache.md
@@ -49,9 +49,9 @@ A reverse proxy is a common setup for serving dynamic web apps. The reverse prox
A proxy server is one which forwards client requests to another server instead of fulfilling requests itself. A reverse proxy forwards to a fixed destination, typically on behalf of arbitrary clients. In this guide, Apache is configured as the reverse proxy running on the same server that Kestrel is serving the ASP.NET Core app.
-Because requests are forwarded by reverse proxy, use the Forwarded Headers Middleware from the [Microsoft.AspNetCore.HttpOverrides](https://www.nuget.org/packages/Microsoft.AspNetCore.HttpOverrides/) package. The middleware updates the `Request.Scheme`, using the `X-Forwarded-Proto` header, so that redirect URIs and other security policies work correctly.
+Because requests are forwarded by reverse proxy, use the [Forwarded Headers Middleware](xref:host-and-deploy/proxy-load-balancer) from the [Microsoft.AspNetCore.HttpOverrides](https://www.nuget.org/packages/Microsoft.AspNetCore.HttpOverrides/) package. The middleware updates the `Request.Scheme`, using the `X-Forwarded-Proto` header, so that redirect URIs and other security policies work correctly.
-When using any type of authentication middleware, the Forwarded Headers Middleware must run first. This ordering ensures that the authentication middleware can consume the header values and generate correct redirect URIs.
+Any component that depends on the scheme, such as authentication, link generation, redirects, and geolocation, must be placed after invoking the Forwarded Headers Middleware. As a general rule, Forwarded Headers Middleware should run before other middleware except diagnostics and error handling middleware. This ordering ensures that the middleware relying on forwarded headers information can consume the header values for processing.
::: moniker range=">= aspnetcore-2.0"
> [!NOTE]
@@ -130,13 +130,17 @@ Complete!
> [!NOTE]
> In this example, the output reflects httpd.86_64 since the CentOS 7 version is 64 bit. To verify where Apache is installed, run `whereis httpd` from a command prompt.
-### Configure Apache for reverse proxy
+### Configure Apache
Configuration files for Apache are located within the `/etc/httpd/conf.d/` directory. Any file with the *.conf* extension is processed in alphabetical order in addition to the module configuration files in `/etc/httpd/conf.modules.d/`, which contains any configuration files necessary to load modules.
Create a configuration file, named *hellomvc.conf*, for the app:
```
+
+ RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+
+
ProxyPreserveHost On
ProxyPass / http://127.0.0.1:5000/
@@ -274,7 +278,7 @@ sudo firewall-cmd --add-port=443/tcp --permanent
Reload the firewall settings. Check the available services and ports in the default zone. Options are available by inspecting `firewall-cmd -h`.
-```bash
+```bash
sudo firewall-cmd --reload
sudo firewall-cmd --list-all
```
@@ -298,6 +302,7 @@ To configure Apache for SSL, the *mod_ssl* module is used. When the *httpd* modu
```bash
sudo yum install mod_ssl
```
+
To enforce SSL, install the `mod_rewrite` module to enable URL rewriting:
```bash
@@ -307,6 +312,10 @@ sudo yum install mod_rewrite
Modify the *hellomvc.conf* file to enable URL rewriting and secure communication on port 443:
```
+
+ RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+
+
RewriteEngine On
RewriteCond %{HTTPS} !=on
@@ -376,7 +385,7 @@ sudo nano /etc/httpd/conf/httpd.conf
Add the line `Header set X-Content-Type-Options "nosniff"`. Save the file. Restart Apache.
-### Load Balancing
+### Load Balancing
This example shows how to setup and configure Apache on CentOS 7 and Kestrel on the same instance machine. In order to not have a single point of failure; using *mod_proxy_balancer* and modifying the **VirtualHost** would allow for managing multiple instances of the web apps behind the Apache proxy server.
@@ -387,6 +396,10 @@ sudo yum install mod_proxy_balancer
In the configuration file shown below, an additional instance of the `hellomvc` app is setup to run on port 5001. The *Proxy* section is set with a balancer configuration with two members to load balance *byrequests*.
```
+
+ RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+
+
RewriteEngine On
RewriteCond %{HTTPS} !=on
@@ -419,6 +432,7 @@ In the configuration file shown below, an additional instance of the `hellomvc`
```
### Rate Limits
+
Using *mod_ratelimit*, which is included in the *httpd* module, the bandwidth of clients can be limited:
```bash
@@ -434,3 +448,7 @@ The example file limits bandwidth as 600 KB/sec under the root location:
```
+
+## Additional resources
+
+* [Configure ASP.NET Core to work with proxy servers and load balancers](xref:host-and-deploy/proxy-load-balancer)
diff --git a/aspnetcore/host-and-deploy/linux-nginx.md b/aspnetcore/host-and-deploy/linux-nginx.md
index 041320801a..25e7c6c3d2 100644
--- a/aspnetcore/host-and-deploy/linux-nginx.md
+++ b/aspnetcore/host-and-deploy/linux-nginx.md
@@ -75,9 +75,9 @@ Kestrel is great for serving dynamic content from ASP.NET Core. However, the web
For the purposes of this guide, a single instance of Nginx is used. It runs on the same server, alongside the HTTP server. Based on requirements, a different setup may be chosen.
-Because requests are forwarded by reverse proxy, use the Forwarded Headers Middleware from the [Microsoft.AspNetCore.HttpOverrides](https://www.nuget.org/packages/Microsoft.AspNetCore.HttpOverrides/) package. The middleware updates the `Request.Scheme`, using the `X-Forwarded-Proto` header, so that redirect URIs and other security policies work correctly.
+Because requests are forwarded by reverse proxy, use the [Forwarded Headers Middleware](xref:host-and-deploy/proxy-load-balancer) from the [Microsoft.AspNetCore.HttpOverrides](https://www.nuget.org/packages/Microsoft.AspNetCore.HttpOverrides/) package. The middleware updates the `Request.Scheme`, using the `X-Forwarded-Proto` header, so that redirect URIs and other security policies work correctly.
-When using any type of authentication middleware, the Forwarded Headers Middleware must run first. This ordering ensures that the authentication middleware can consume the header values and generate correct redirect URIs.
+Any component that depends on the scheme, such as authentication, link generation, redirects, and geolocation, must be placed after invoking the Forwarded Headers Middleware. As a general rule, Forwarded Headers Middleware should run before other middleware except diagnostics and error handling middleware. This ordering ensures that the middleware relying on forwarded headers information can consume the header values for processing.
# [ASP.NET Core 2.x](#tab/aspnetcore2x)
@@ -156,6 +156,8 @@ server {
proxy_set_header Connection keep-alive;
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+ proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
@@ -357,3 +359,5 @@ Add the line `add_header X-Content-Type-Options "nosniff";` and save the file, t
## Additional resources
* [Nginx: Binary Releases: Official Debian/Ubuntu packages](https://www.nginx.com/resources/wiki/start/topics/tutorials/install/#official-debian-ubuntu-packages)
+* [Configure ASP.NET Core to work with proxy servers and load balancers](xref:host-and-deploy/proxy-load-balancer)
+* [NGINX: Using the Forwarded header](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/)
diff --git a/aspnetcore/host-and-deploy/proxy-load-balancer.md b/aspnetcore/host-and-deploy/proxy-load-balancer.md
index 7e0c08ff7f..71ee38a0e1 100644
--- a/aspnetcore/host-and-deploy/proxy-load-balancer.md
+++ b/aspnetcore/host-and-deploy/proxy-load-balancer.md
@@ -32,7 +32,7 @@ By convention, proxies forward information in HTTP headers.
| 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](https://github.com/aspnet/Announcements/issues/295) 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](https://www.nuget.org/packages/Microsoft.AspNetCore.HttpOverrides/) package, reads these headers and fills in the associated fields on [HttpContext](/dotnet/api/microsoft.aspnetcore.http.httpcontext).
+The Forwarded Headers Middleware, from the [Microsoft.AspNetCore.HttpOverrides](https://www.nuget.org/packages/Microsoft.AspNetCore.HttpOverrides/) package, reads these headers and fills in the associated fields on [HttpContext](/dotnet/api/microsoft.aspnetcore.http.httpcontext).
The middleware updates:
@@ -61,7 +61,7 @@ Configure the middleware with [ForwardedHeadersOptions](/dotnet/api/microsoft.as
public void ConfigureServices(IServiceCollection services)
{
services.AddMvc();
-
+
services.Configure(options =>
{
options.ForwardedHeaders =
@@ -92,6 +92,14 @@ public void Configure(IApplicationBuilder app, IHostingEnvironment env)
> [!NOTE]
> If no [ForwardedHeadersOptions](/dotnet/api/microsoft.aspnetcore.builder.forwardedheadersoptions) are specified in `Startup.ConfigureServices` or directly to the extension method with [UseForwardedHeaders(IApplicationBuilder, ForwardedHeadersOptions)](/dotnet/api/microsoft.aspnetcore.builder.forwardedheadersextensions.useforwardedheaders?view=aspnetcore-2.0#Microsoft_AspNetCore_Builder_ForwardedHeadersExtensions_UseForwardedHeaders_Microsoft_AspNetCore_Builder_IApplicationBuilder_Microsoft_AspNetCore_Builder_ForwardedHeadersOptions_), the default headers to forward are [ForwardedHeaders.None](/dotnet/api/microsoft.aspnetcore.httpoverrides.forwardedheaders). The [ForwardedHeadersOptions.ForwardedHeaders](/dotnet/api/microsoft.aspnetcore.builder.forwardedheadersoptions.forwardedheaders) property must be configured with the headers to forward.
+## Nginx configuration
+
+To forward the `X-Forwarded-For` and `X-Forwarded-Proto` headers, see [Host on Linux with Nginx: Configure Nginx](xref:host-and-deploy/linux-nginx#configure-nginx). For more information, see [NGINX: Using the Forwarded header](https://www.nginx.com/resources/wiki/start/topics/examples/forwarded/).
+
+## Apache configuration
+
+`X-Forwarded-For` is added automatically (see [Apache Module mod_proxy: Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers)). For information on how to forward the `X-Forwarded-Proto` header, see [Host on Linux with Apache: Configure Apache](xref:host-and-deploy/linux-apache#configure-apache).
+
## Forwarded Headers Middleware options
[ForwardedHeadersOptions](/dotnet/api/microsoft.aspnetcore.builder.forwardedheadersoptions) control the behavior of the Forwarded Headers Middleware: