README.md

ProxyKit HttpOverrides

Introduction

Applications that are deployed behind a reverse proxy typically need to be aware of that so they can generate correct URLs and paths when responding to requests. That is, they look at X-Forward-* / Forwarded headers and use their values accordingly.

In ASP.NET Core, this means using the ForwardedHeaders middleware in your application. However, this middleware does not support X-Forwarded-PathBase that tells upstream hosts what the path of the incoming request is. For example, if you proxy http://example.com/foo/ to http://upstream-host/ the /foo/ part is lost and absolute URLs cannot be generated unless you configure your application's PathBase directly using app.UsePathBase().

However, the problems with app.UsePathBase() are:

• You need to know the value at deployment time coupling knowledge of your reverse proxy configuration with your application.
• The value is used at start up time meaning if you want to change your reverse proxy routing configuration you have to restart your application.
• Your application can only support one path base at a time. If you want your reverse proxy to forward two or more routes to a single upstream host, you are out of luck.

Related issues and discussions:

• dotnet/aspnetcore#5978
• dotnet/aspnetcore#5898

This project extends ForwardedHeaders with support for X-Forwarded-PathBase that allows the path base to be determined at runtime / per request basis.

Using

Install the NuGet package:

dotnet package add ProxyKit.HttpOverrides

As this package extends ASP.NET Cores ForwardedHeadersMiddleware use it instead UseForwardedHeaders() in your Startup.ConfiguratApplication():

var options = new ForwardedHeadersWithPathBaseOptions
{
   ForwardedHeaders = ForwardedHeadersWithPathBase.All
};
app.UseForwardedHeadersWithPathBase(options);

ForwardedHeadersWithPathBaseOptions extends ForwardedHeadersOptions with additional properties that follows the same patterns of the base class:

• ForwardedPathBaseHeaderName - the PathBase header to look for defaulting to X-Forwarded-PathBase
• OriginalPathBaseHeaderName - the header to add that will contain the original path base if it has been applied, defaulting to X-Original-PathBase.

Please refer to the ForwaredHeadersMiddleware documentation for correct usage of other properties (and note the security advisory!).

How to build

The build requires Docker to ensure portability with CI.

On Windows:

.\build.cmd

On Linux:

./build.sh

To build without docker, .NET Core SDK 3.1 is required.

On Windows:

.\build-local.cmd

On Linux:

./build-local.sh

Contributing / Feedback / Questions

Any ideas for features, bugs or questions, please create an issue. Pull requests gratefully accepted but please create an issue for discussion first.

I can be reached on twitter at @randompunter