Scenario: running behind a reverse proxy

Many sites put a reverse proxy in front of every web application: it terminates TLS with the site certificate, applies the site’s access rules and writes the access log. The Router gateway works behind one. This page lists what the proxy and the gateway each need.

caller --HTTPS--> reverse proxy --HTTP--> gateway --transport--> services

The gateway code is the gateway of Getting started. The proxy configuration below is an nginx example; it was not run with that gateway. Translate it to your proxy.

The gateway side

Two parts of the sample gateway matter behind a proxy.

Forwarded headers. Take the caller’s address and scheme from the proxy’s X-Forwarded-For and X-Forwarded-Proto, from the proxy’s address only:

// Behind a reverse proxy: take the caller's address and scheme from X-Forwarded-For and
// X-Forwarded-Proto, but only from the proxies listed in ReverseProxy:KnownProxies (loopback by default).
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    foreach (var proxy in builder.Configuration.GetSection("ReverseProxy:KnownProxies").Get<string[]>() ?? [])
    {
        options.KnownProxies.Add(IPAddress.Parse(proxy));
    }
});

app.UseForwardedHeaders() must run before the gateway’s middleware, as it does in the sample. Without a known proxy entry, ASP.NET Core accepts forwarded headers only from the loopback address. List the proxy’s address in configuration:

{
  "ReverseProxy": {
    "KnownProxies": [ "10.0.0.5" ]
  }
}

Identity headers. The gateway removes the identity headers a caller sends and conveys the caller only in its signed identity envelope (Router gateway host). The sample also removes every other X-StellaOps-* request header:

// Optional hardening: the gateway host already removes the identity headers (X-StellaOps-Tenant,
// X-StellaOps-Scopes, the identity envelope and the rest) from every routed request. This middleware
// also removes every other X-StellaOps-* request header, so no caller-supplied one reaches a service.
app.Use((context, next) =>
{
    foreach (var name in context.Request.Headers.Keys
                 .Where(key => key.StartsWith("X-StellaOps-", StringComparison.OrdinalIgnoreCase))
                 .ToList())
    {
        context.Request.Headers.Remove(name);
    }

    return next(context);
});

The .NET tool host needs no such middleware.

The .NET tool behind a proxy

The tool stellaops-router-gateway has no ReverseProxy:KnownProxies setting and does not add the forwarded-headers code above. Set the environment variable ASPNETCORE_FORWARDEDHEADERS_ENABLED=true for it: ASP.NET Core then takes the caller’s address and scheme from X-Forwarded-For and X-Forwarded-Proto.

That variable accepts the forwarded headers from any address, not only from the proxy. Make the gateway’s HTTP port reachable from the proxy only (bind it to the proxy’s network, or filter it), so that no caller can send the headers directly. When you need a list of known proxies, compose the gateway in your own host as the sample does.

The proxy side

SettingWhy
Pass Host, X-Forwarded-For, X-Forwarded-ProtoWith forwarded headers, the gateway’s logs and any code that reads the caller’s address see the caller, not the proxy.
Optionally clear X-StellaOps-* request headersThe gateway removes the identity headers itself; clearing them in the proxy too is defence in depth (Security).
Turn off request and response buffering on upload and download pathsA buffering proxy holds a whole upload or download before it passes it on, in addition to the gateway.
Read timeout above Gateway:Routing:GlobalTimeoutCapOtherwise the proxy closes long requests before the gateway answers.
Body size limit at least the gateway’sOtherwise the proxy refuses uploads first.
Do not expose the transport portsOnly the gateway’s HTTP port goes behind the proxy. Services connect to the transport ports directly.

An nginx example for a gateway on 127.0.0.1:8080, with upload and download paths under /reports/:

upstream router_gateway {
    server 127.0.0.1:8080;
}

server {
    listen 443 ssl;
    server_name api.contoso.example;
    ssl_certificate     /etc/nginx/tls/api.contoso.example.crt;
    ssl_certificate_key /etc/nginx/tls/api.contoso.example.key;

    client_max_body_size 30m;
    proxy_read_timeout   130s;

    location / {
        proxy_pass http://router_gateway;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # An empty value removes the header from the proxied request.
        proxy_set_header X-StellaOps-Actor    "";
        proxy_set_header X-StellaOps-TenantId "";
        proxy_set_header X-StellaOps-Scopes   "";
        proxy_set_header X-StellaOps-Roles    "";
        proxy_set_header X-StellaOps-Session  "";
        proxy_set_header X-StellaOps-Identity-Envelope "";
    }

    location ~ ^/reports/ {
        proxy_pass http://router_gateway;
        proxy_http_version 1.1;
        proxy_request_buffering off;
        proxy_buffering off;
        proxy_set_header Host              $host;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-StellaOps-Actor    "";
        proxy_set_header X-StellaOps-TenantId "";
        proxy_set_header X-StellaOps-Scopes   "";
        proxy_set_header X-StellaOps-Roles    "";
        proxy_set_header X-StellaOps-Session  "";
        proxy_set_header X-StellaOps-Identity-Envelope "";
    }
}

The gateway removes these headers itself; clearing them here is defence in depth. nginx can only clear headers it names, so list each one.

Health checks

Point the proxy’s or the platform’s health check at the gateway directly, not through a routed path:

PathAnswers
/health/live200 while the process runs
/health/ready200 when the gateway can serve
/healthThe overall state, with the licence detail

Pitfalls