Konfigurieren von ASP.NET Core zur Verwendung mit Proxyservern und Lastenausgleich

In der für ASP.NET Core empfohlenen Konfiguration wird die App mit dem ASP.NET Core-Modul (ANCM) für IIS, Nginx oder Apache gehostet. Proxyserver, Lastenausgleichsmodule und anderen Netzwerkgeräte verdecken häufig Informationen über die Anforderung, bevor diese die App erreicht:

• Wenn HTTPS-Anforderungen über HTTP-Proxy ausgeführt werden, geht das ursprüngliche Schema (HTTPS) verloren und muss in einem Header weitergeleitet werden.
• Da eine App eine Anforderung über den Proxy empfängt und nicht über ihre echte Quelle im Internet oder Unternehmensnetzwerk, muss die ursprüngliche Client-IP-Adresse ebenfalls in einem Header weitergeleitet werden.

Diese Informationen können im Anforderungsprozess, z.B. in Umleitungen, bei der Authentifizierung, der Linkgenerierung, der Richtlinienauswertung und der Client-Geolocation wichtig sein.

Informationen zu Apps, die in einer Webfarm ausgeführt werden sollen, finden Sie unterHosten von ASP.NET Core in einer Webfarm.

Weitergeleitete Header

Gemäß der Konvention leiten Proxys Informationen in HTTP-Headern weiter.

Die Middleware für weitergeleitete Header, ForwardedHeadersMiddleware, liest die Header und füllt die zugehörigen Felder in HttpContext aus.

Die Middleware aktualisiert:

• HttpContext.Connection.RemoteIpAddress: Wird mit dem Headerwert X-Forwarded-For festgelegt. Zusätzliche Einstellungen beeinflussen, wie die Middleware RemoteIpAddress festlegt. Einzelheiten finden Sie unter Middleware für weitergeleitete Header: Optionen. Die genutzten Werte werden aus X-Forwarded-For entfernt, und die alten Werte von HttpContext.Connection.RemoteIpAddress werden in X-Original-For beibehalten. Hinweis: Dieser Vorgang kann mehrmals wiederholt werden, wenn mehrere Werte in X-Forwarded-For/Proto/Host/Prefix vorhanden sind, was dazu führt, dass mehrere Werte nach X-Original-* verschoben werden, einschließlich des ursprünglichen RemoteIpAddress/Host/Scheme/PathBase.
• HttpContext.Request.Scheme: Wird mit dem Headerwert X-Forwarded-Proto festgelegt. Die genutzten Werte werden aus X-Forwarded-Proto entfernt, und die alten Werte von HttpContext.Request.Scheme werden in X-Original-Proto beibehalten.
• HttpContext.Request.Host: Wird mit dem Headerwert X-Forwarded-Host festgelegt. Die genutzten Werte werden aus X-Forwarded-Host entfernt, und die alten Werte von HttpContext.Request.Host werden in X-Original-Host beibehalten.
• HttpContext.Request.PathBase: Wird mit dem Headerwert X-Forwarded-Prefix festgelegt. Die genutzten Werte werden aus X-Forwarded-Prefix entfernt, und die alten Werte von HttpContext.Request.PathBase werden in X-Original-Prefix beibehalten.

Weitere Informationen hierzu finden Sie in diesem GitHub-Issue.

Die Standardeinstellungen der Middleware für weitergeleitete Header können konfiguriert werden. Für die Standardeinstellungen:

• Zwischen App und Quelle der Anforderungen ist nur ein Proxy vorhanden.
• Loopbackadressen sind für bekannte Proxys und bekannte Netzwerke konfiguriert.
• Die weitergeleiteten Kopfzeilen werden X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host und X-Forwarded-Prefixbenannt.
• Der Wert ForwardedHeaders lautet ForwardedHeaders.None, und die gewünschten Forwarder müssen hier festgelegt werden, um die Middleware zu aktivieren.

Beachten Sie, dass bei manchen Netzwerkgeräten eine zusätzliche Konfiguration erforderlich ist, damit die Header X-Forwarded-For und X-Forwarded-Proto hinzugefügt werden. Lesen Sie in der Anleitung des Geräteherstellers nach, wenn über einen Proxy übermittelte Anfragen ohne diese Header in der Anwendung eingehen. Verwendet das Gerät andere Headernamen als X-Forwarded-For und X-Forwarded-Proto, passen Sie die Optionen ForwardedForHeaderName und ForwardedProtoHeaderName entsprechend an. Weitere Informationen finden Sie in den Abschnitten Middleware für weitergeleitete Header: Optionen und Konfiguration für einen Proxy, der andere Headernamen nutzt.

IIS-/IIS Express und ASP.NET Core-Modul

Middleware für weitergeleitete Header wird standardmäßig durch Middleware für die Integration von IIS aktiviert, wenn die App hinter IIS und dem ASP.NET Core-Modul (ANCM) für IIS von einem Out-of-Process-Host gehostet wird. Middleware für weitergeleitete Header wird aktiviert, damit sie zuerst in der Middlewarepipeline mit einer eingeschränkten Konfiguration speziell für das ASP.NET Core-Modul ausgeführt wird. Die eingeschränkte Konfiguration wird aufgrund der Sicherheitsbedenken bei weitergeleiteten Headern angewendet, z. B. im Hinblick auf IP-Spoofing. Die Middleware wird so konfiguriert, dass sie die Header X-Forwarded-For und X-Forwarded-Proto weiterleitet, und ist auf einen einzelnen localhost-Proxy beschränkt. Wenn zusätzliche Konfigurationsschritte erforderlich sind, finden Sie weitere Informationen unter Middleware für weitergeleitete Header: Optionen.

Andere Proxyserver- und Lastenausgleichsszenarios

Abgesehen von der Verwendung zur IIS-Integration wird Middleware für weitergeleitete Header beim Out-of-Process-Hosting nicht standardmäßig aktiviert. Middleware für weitergeleitete Header muss aktiviert sein, damit eine App weitergeleitete Header mit UseForwardedHeaders verarbeitet. Sind nach der Aktivierung der Middleware keine ForwardedHeadersOptions für die Middleware angegeben, sind die standardmäßigen ForwardedHeadersOptions gleich ForwardedHeaders.None.

Konfigurieren Sie die Middleware mit ForwardedHeadersOptions so, dass die Header X-Forwarded-For und X-Forwarded-Proto weitergeleitet werden.

Middleware für weitergeleitete Header: Auftrag

Middleware für weitergeleitete Header muss vor anderen Middlewarekomponenten ausgeführt werden. Mit dieser Reihenfolge wird sichergestellt, dass die auf Informationen von weitergeleiteten Headern basierende Middleware die zu verarbeitenden Headerwerte nutzen kann. Die Middleware für weitergeleitete Header kann nach der Diagnose und Fehlerbehandlung ausgeführt werden. Sie muss jedoch vor dem Aufrufen von UseHstsausgeführt werden:

using Microsoft.AspNetCore.HttpOverrides;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseForwardedHeaders();
    app.UseHsts();
}
else
{
    app.UseDeveloperExceptionPage();
    app.UseForwardedHeaders();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Rufen Sie alternativ vor der Diagnose UseForwardedHeaders auf:

using Microsoft.AspNetCore.HttpOverrides;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});

var app = builder.Build();

app.UseForwardedHeaders();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Nginx-Konfiguration

Informationen zur Weiterleitung der Header X-Forwarded-For und X-Forwarded-Proto finden Sie unter X-Forwarded-For. Weitere Informationen finden Sie unter NGINX: Using the Forwarded header (NGINX: Verwenden des weitergeleiteten Headers).

Apache-Konfiguration

X-Forwarded-For wird automatisch hinzugefügt. Weitere Informationen finden Sie unter Apache-Modul mod_proxy: Reverseproxy-Anforderungsheader.

Middleware für weitergeleitete Header: Optionen

ForwardedHeadersOptions steuern das Verhalten der ForwardedHeadersOptions. Im folgenden Beispiel werden die Standardwerte geändert:

• Die Anzahl von Einträgen in den weitergeleiteten Headern wird auf 2 beschränkt.
• Es wird die bekannte Proxyadresse 127.0.10.1 hinzugefügt.
• Der Name des weitergeleiteten Headers wird vom Standardwert X-Forwarded-For in den Wert X-Forwarded-For-My-Custom-Header-Name geändert.

using System.Net;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardLimit = 2;
    options.KnownProxies.Add(IPAddress.Parse("127.0.10.1"));
    options.ForwardedForHeaderName = "X-Forwarded-For-My-Custom-Header-Name";
});

var app = builder.Build();

app.UseForwardedHeaders();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Szenarios und Anwendungsfälle

Wenn keine weitergeleiteten Header hinzugefügt werden können und alle Anforderungen sicher sind

In einigen Fällen ist es möglicherweise ausgeschlossen, weitergeleitete Header den Anforderungen hinzuzufügen, die über einen Proxy an die App übermittelt werden. Wenn der Proxy erzwingt, dass alle öffentlichen externen Anforderungen HTTPS-Anforderungen sein müssen, kann das Schema manuell festgelegt werden, bevor ein beliebiger Middlewaretyp verwendet wird:

using Microsoft.AspNetCore.HttpOverrides;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});

var app = builder.Build();

app.Use((context, next) =>
{
    context.Request.Scheme = "https";
    return next(context);
});

app.UseForwardedHeaders();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Dieser Code kann mit einer Umgebungsvariablen oder einer anderen Konfigurationseinstellung in einer Entwicklungs- oder Stagingumgebung deaktiviert werden:

using Microsoft.AspNetCore.HttpOverrides;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});

var app = builder.Build();

if (!app.Environment.IsProduction())
{
    app.Use((context, next) =>
    {
        context.Request.Scheme = "https";
        return next(context);
    });
}

app.UseForwardedHeaders();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Arbeiten mit Pfadbasis und Proxys, die den Anforderungspfad ändern

Einige Proxys übergeben den Pfad intakt, aber mit einem App-basierten Pfad, der entfernt werden sollte, damit das Routing ordnungsgemäß funktioniert. UsePathBaseExtensions.UsePathBase-Middleware teilt den Pfad in HttpRequest.Path und den App-Basispfad in HttpRequest.PathBase.

Wenn /foo der App-Basispfad für einen als /foo/api/1 übergebenen Proxypfad ist, setzt die Middleware mit dem folgenden Befehl Request.PathBase auf /foo und Request.Path auf /api/1:

app.UsePathBase("/foo");
// ...
app.UseRouting();

Der ursprüngliche Pfad und die Pfadbasis werden erneut angewendet, wenn die Middleware in umgekehrter Reihenfolge erneut aufgerufen wird. Weitere Informationen zur Reihenfolge der Middlewareverarbeitung finden Sie unter ASP.NET Core-Middleware.

Wenn der Proxy den Pfad abschneidet (z.B. Weiterleitung von /foo/api/1 zu /api/1), korrigieren Sie Umleitungen und Links, indem Sie die Eigenschaft /foo/api/1 der Anforderungen setzen:

app.Use((context, next) =>
{
    context.Request.PathBase = new PathString("/foo");
    return next(context);
});

Wenn der Proxy Pfaddaten hinzufügt, verwerfen Sie einen Teil des Pfads, um Umleitungen und Links zu korrigieren, indem Sie StartsWithSegments verwenden und der Path-Eigenschaft zuweisen:

app.Use((context, next) =>
{
    if (context.Request.Path.StartsWithSegments("/foo", out var remainder))
    {
        context.Request.Path = remainder;
    }

    return next(context);
});

Konfiguration für einen Proxy, der andere Headernamen verwendet

Verwendet der Proxy zum Weiterleiten der Proxyadresse/des Ports und zum Erzeugen der Schemainformationen andere Headernamen als X-Forwarded-For und X-Forwarded-Proto, passen Sie die Optionen ForwardedForHeaderName und ForwardedProtoHeaderName entsprechend an:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedForHeaderName = "HeaderNamUsedByProxy_X-Forwarded-For_Header";
    options.ForwardedProtoHeaderName = "HeaderNamUsedByProxy_X-Forwarded-Proto_Header";
});

var app = builder.Build();

app.UseForwardedHeaders();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Das Schema für Linux- und Nicht-IIS-Reverseproxys weiterleiten

Apps, die UseHttpsRedirection und UseHsts aufrufen, versetzen eine Site in eine Endlosschleife, falls die Bereitstellung in einem Azure Linux App Service, auf einem virtuellen Azure Linux-Computer, oder hinter einem anderen Reverseproxy als IIS erfolgt. TLS wird vom Reverseproxy beendet, und Kestrel wird nicht auf das richtige Anforderungsschema aufmerksam gemacht. OAuth und OIDC schlagen in dieser Konfiguration ebenfalls fehl, weil sie falsche Umleitungen generieren. UseIISIntegration fügt die Middleware für weitergeleitete Header hinzu und konfiguriert sie, wenn es hinter IIS ausgeführt wird, aber es gibt keine entsprechende automatische Konfiguration für Linux (Apache- oder Nginx-Integration).

Um das Schema aus dem Proxy in Nicht-IIS-Szenarien weiterzuleiten, aktivieren Sie die Middleware für weitergeleitete Header, indem Sie ASPNETCORE_FORWARDEDHEADERS_ENABLED auf true festlegen. Warnung: Dieses Flag verwendet Einstellungen für Cloudumgebungen und aktiviert keine Features wie die KnownProxies option, um einzuschränken, von welchen IPs Weiterleitungen akzeptiert werden.

Zertifikatweiterleitung

Azure

Informationen zum Konfigurieren von Azure App Service für die Zertifikatsweiterleitung finden Sie unter Konfigurieren der gegenseitigen TLS-Authentifizierung für Azure App Service. Die folgende Anleitung bezieht sich auf die Konfiguration der ASP.NET Core-App.

• Konfigurieren Sie Middleware für die Zertifikatweiterleitung, um den von Azure verwendeten Headernamen anzugeben. Fügen Sie den folgenden Code hinzu, um den Header zu konfigurieren, anhand dessen die Middleware ein Zertifikat erstellt.
• Rufen Sie UseCertificateForwarding vor UseAuthentication auf.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddCertificateForwarding(options =>
    options.CertificateHeader = "X-ARR-ClientCert");

var app = builder.Build();

app.UseCertificateForwarding();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();
app.UseAuthentication();

app.MapRazorPages();

app.Run();

Andere Webproxys

Wenn ein Proxy verwendet wird, der nicht IIS oder Routing von Anwendungsanforderungen von Azure App Service entspricht, konfigurieren Sie den Proxy so, dass das empfangene Zertifikat in einem HTTP-Header weitergeleitet wird.

• Konfigurieren Sie Middleware für die Zertifikatweiterleitung, um den Headernamen anzugeben. Fügen Sie den folgenden Code hinzu, um den Header zu konfigurieren, anhand dessen die Middleware ein Zertifikat erstellt.
• Rufen Sie UseCertificateForwarding vor UseAuthentication auf.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddCertificateForwarding(options =>
    options.CertificateHeader = "YOUR_CERTIFICATE_HEADER_NAME");

var app = builder.Build();

app.UseCertificateForwarding();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();
app.UseAuthentication();

app.MapRazorPages();

app.Run();

Wenn der Proxy keine Base64-Codierung für das Zertifikat verwendet (wie bei Nginx), legen Sie die Option HeaderConverter fest. Betrachten Sie das folgenden Beispiel:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddCertificateForwarding(options =>
{
    options.CertificateHeader = "YOUR_CUSTOM_HEADER_NAME";
    options.HeaderConverter = (headerValue) =>
    {
        // Conversion logic to create an X509Certificate2.
        var clientCertificate = ConversionLogic.CreateAnX509Certificate2();
        return clientCertificate;
    };
});

var app = builder.Build();

app.UseCertificateForwarding();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();
app.UseAuthentication();

app.MapRazorPages();

app.Run();

Problembehandlung

Wenn Header nicht wie erwartet weitergeleitet werden, aktivieren Sie die debug auf debug-Ebene und die HTTP-Anforderungsprotokollierung. UseHttpLogging muss nach UseForwardedHeaders aufgerufen werden:

using Microsoft.AspNetCore.HttpLogging;
using Microsoft.AspNetCore.HttpOverrides;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddHttpLogging(options =>
{
    options.LoggingFields = HttpLoggingFields.RequestPropertiesAndHeaders;
});

builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
});

var app = builder.Build();

app.UseForwardedHeaders();
app.UseHttpLogging();

app.Use(async (context, next) =>
{
    // Connection: RemoteIp
    app.Logger.LogInformation("Request RemoteIp: {RemoteIpAddress}",
        context.Connection.RemoteIpAddress);

    await next(context);
});

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Wenn in einem bestimmten Header mehrere Werte vorhanden sind, verarbeitet die Middleware der Weiterleitungsheader die Header in umgekehrter Reihenfolge von rechts nach links. Der Standardwert von ForwardLimit ist 1 (eins), sodass nur der äußere rechte Wert aus den Headern verarbeitet wird, es sei denn, der Wert von ForwardLimit wird erhöht.

Die ursprüngliche IP-Remoteadresse der Anforderung muss mit einem Eintrag in den KnownProxies- oder KnownNetworks-Listen übereinstimmen, bevor weitergeleitete Header verarbeitet werden. Auf diese Weise wird das Headerspoofing begrenzt, da keine Weiterleitungen von nicht vertrauenswürdigen Proxys akzeptiert werden. Wenn ein unbekannter Proxy erkannt wird, gibt die Protokollierung die Adresse des Proxys an:

September 20th 2018, 15:49:44.168 Unknown proxy: 10.0.0.100:54321

Im vorherigen Beispiel ist 10.0.0.100 ein Proxyserver. Wenn der Server ein vertrauenswürdiger Proxy ist, fügen Sie KnownNetworks die IP-Adresse des Servers KnownProxies oder ein vertrauenswürdiges Netzwerk hinzu. Weitere Informationen finden Sie im Abschnitt Middleware für weitergeleitete Header: Optionen.

using Microsoft.AspNetCore.HttpOverrides;
using System.Net;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    options.KnownProxies.Add(IPAddress.Parse("10.0.0.100"));
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseForwardedHeaders();
    app.UseHsts();
}
else
{
    app.UseDeveloperExceptionPage();
    app.UseForwardedHeaders();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Um die Protokolle anzuzeigen, fügen Sie "Microsoft.AspNetCore.HttpLogging": "Information" der Datei appsettings.Development.json hinzu:

{
  "DetailedErrors": true,
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.AspNetCore.HttpLogging": "Information"
    }
  }
}

Zusätzliche Ressourcen

• Hosten von ASP.NET Core in einer Webfarm
• Microsoft Security Advisory CVE-2018-0787: ASP.NET Core Elevation Of Privilege Vulnerability (Microsoft-Sicherheitsempfehlung CVE-2018-0787: Sicherheitsrisiko durch Rechteerweiterungen in ASP.NET Core)
• YARP: Yet Another Reverse Proxy (ein weiterer Reverseproxy)

In der für ASP.NET Core empfohlenen Konfiguration wird die App mit dem IIS/ASP.NET Core-Modul, Nginx oder Apache gehostet. Proxyserver, Lastenausgleichsmodule und anderen Netzwerkgeräte verdecken häufig Informationen über die Anforderung, bevor diese die App erreicht:

• Wenn HTTPS-Anforderungen über HTTP-Proxy ausgeführt werden, geht das ursprüngliche Schema (HTTPS) verloren und muss in einem Header weitergeleitet werden.
• Da eine App eine Anforderung über den Proxy empfängt und nicht über ihre echte Quelle im Internet oder Unternehmensnetzwerk, muss die ursprüngliche Client-IP-Adresse ebenfalls in einem Header weitergeleitet werden.

Diese Informationen können im Anforderungsprozess, z.B. in Umleitungen, bei der Authentifizierung, der Linkgenerierung, der Richtlinienauswertung und der Client-Geolocation wichtig sein.

Weitergeleitete Header

Gemäß der Konvention leiten Proxys Informationen in HTTP-Headern weiter.

Die Middleware für weitergeleitete Header (ForwardedHeadersMiddleware) liest die Header und füllt die zugehörigen Felder in HttpContext aus.

Die Middleware aktualisiert:

• HttpContext.Connection.RemoteIpAddress: Wird über den Headerwert X-Forwarded-For festgelegt. Zusätzliche Einstellungen beeinflussen, wie die Middleware RemoteIpAddress festlegt. Einzelheiten finden Sie unter Middleware für weitergeleitete Header: Optionen. Die genutzten Werte werden aus X-Forwarded-For entfernt, und die alten Werte werden in X-Original-For beibehalten. Das gleiche Muster wird auf die anderen Header (Host und Proto) angewendet.
• HttpContext.Request.Scheme: Wird über den Headerwert X-Forwarded-Proto festgelegt.
• HttpContext.Request.Host: Wird über den Headerwert X-Forwarded-Host festgelegt.

Weitere Informationen hierzu finden Sie in diesem GitHub-Issue.

Die Standardeinstellungen der Middleware für weitergeleitete Header können konfiguriert werden. Für die Standardeinstellungen:

• Zwischen App und Quelle der Anforderungen ist nur ein Proxy vorhanden.
• Loopbackadressen sind für bekannte Proxys und bekannte Netzwerke konfiguriert.
• Die weitergeleiteten Header heißen X-Forwarded-For und X-Forwarded-Proto.
• Der Wert ForwardedHeaders lautet ForwardedHeaders.None, und die gewünschten Forwarder müssen hier festgelegt werden, um die Middleware zu aktivieren.

Beachten Sie, dass bei manchen Netzwerkgeräten eine zusätzliche Konfiguration erforderlich ist, damit die Header X-Forwarded-For und X-Forwarded-Proto hinzugefügt werden. Lesen Sie in der Anleitung des Geräteherstellers nach, wenn über einen Proxy übermittelte Anfragen ohne diese Header in der Anwendung eingehen. Verwendet das Gerät andere Headernamen als X-Forwarded-For und X-Forwarded-Proto, passen Sie die Optionen ForwardedForHeaderName und ForwardedProtoHeaderName entsprechend an. Weitere Informationen finden Sie in den Abschnitten Middleware für weitergeleitete Header: Optionen und Konfiguration für einen Proxy, der andere Headernamen nutzt.

IIS-/IIS Express und ASP.NET Core-Modul

Middleware für weitergeleitete Header wird standardmäßig durch Middleware für die Integration von IIS aktiviert, wenn die App hinter IIS und dem ASP.NET Core-Modul von einem Out-of-Process-Host gehostet wird. Middleware für weitergeleitete Header wird aktiviert und zuerst in der Middlewarepipeline mit einer beschränkten Konfiguration ausgeführt, die für das ASP.NET Core-Modul spezifisch ist. Dies ist auf Bedenken in Bezug auf die Vertrauenswürdigkeit von weitergeleiteten Headern zurückzuführen (z.B. IP-Spoofing). Die Middleware wird so konfiguriert, dass sie die Header X-Forwarded-For und X-Forwarded-Proto weiterleitet, und ist auf einen einzelnen localhost-Proxy beschränkt. Wenn zusätzliche Konfigurationsschritte erforderlich sind, finden Sie weitere Informationen unter Middleware für weitergeleitete Header: Optionen.

Andere Proxyserver- und Lastenausgleichsszenarios

Außer bei der Verwendung der Integration von IIS wird die Middleware für weitergeleitete Header nicht standardmäßig aktiviert, wenn sie von einem Out-of-Process-Host gehostet wird. Middleware für weitergeleitete Header muss aktiviert sein, damit eine App weitergeleitete Header mit UseForwardedHeaders verarbeitet. Sind nach der Aktivierung der Middleware keine ForwardedHeadersOptions für die Middleware angegeben, sind die standardmäßigen ForwardedHeadersOptions gleich ForwardedHeaders.None.

Konfigurieren Sie die Middleware mit ForwardedHeadersOptions so, dass die Header X-Forwarded-For und X-Forwarded-Proto in Startup.ConfigureServices weitergeleitet werden.

Middleware für weitergeleitete Header: Auftrag

Middleware für weitergeleitete Header muss vor anderen Middlewarekomponenten ausgeführt werden. Mit dieser Reihenfolge wird sichergestellt, dass die auf Informationen von weitergeleiteten Headern basierende Middleware die zu verarbeitenden Headerwerte nutzen kann. Die Middleware für weitergeleitete Header kann nach der Diagnose und Fehlerbehandlung ausgeführt werden. Sie muss jedoch vor dem Aufrufen von UseHstsausgeführt werden:

public class Startup
{
    public Startup(IConfiguration configuration)
    {
        Configuration = configuration;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllersWithViews();
        services.Configure<ForwardedHeadersOptions>(options =>
        {
            options.ForwardedHeaders =
                ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
        });
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
            app.UseForwardedHeaders();
        }
        else
        {
            app.UseExceptionHandler("/Home/Error");
            app.UseForwardedHeaders();
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();

        app.UseRouting();

        app.UseAuthorization();

        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllerRoute(
                name: "default",
                pattern: "{controller=Home}/{action=Index}/{id?}");
        });
    }
}

Rufen Sie alternativ vor der Diagnose UseForwardedHeaders auf:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    app.UseForwardedHeaders();

    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Home/Error");
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllerRoute(
            name: "default",
            pattern: "{controller=Home}/{action=Index}/{id?}");
    });
}

Nginx-Konfiguration

Informationen zur Weiterleitung der Header X-Forwarded-For und X-Forwarded-Proto finden Sie unter X-Forwarded-For. Weitere Informationen finden Sie unter NGINX: Using the Forwarded header (NGINX: Verwenden des weitergeleiteten Headers).

Apache-Konfiguration

X-Forwarded-For wird automatisch hinzugefügt (siehe X-Forwarded-For).

Middleware für weitergeleitete Header: Optionen

ForwardedHeadersOptions steuern das Verhalten der Middleware für weitergeleitete Header. Im folgenden Beispiel werden die Standardwerte geändert:

• Beschränken Sie die Zahl der Einträge in den weitergeleiteten Headern auf 2.
• Fügen Sie eine bekannte Proxyadresse von 127.0.10.1 hinzu.
• Ändern Sie den Namen des weitergeleiteten Headers vom Standardwert X-Forwarded-For in den Wert X-Forwarded-For-My-Custom-Header-Name.

services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardLimit = 2;
    options.KnownProxies.Add(IPAddress.Parse("127.0.10.1"));
    options.ForwardedForHeaderName = "X-Forwarded-For-My-Custom-Header-Name";
});

Szenarios und Anwendungsfälle

Wenn keine weitergeleiteten Header hinzugefügt werden können und alle Anforderungen sicher sind

In einigen Fällen ist es möglicherweise ausgeschlossen, weitergeleitete Header den Anforderungen hinzuzufügen, die über einen Proxy an die App übermittelt werden. Wenn der Proxy erzwingt, dass alle öffentlichen externen Anforderungen HTTPS-Anforderungen sind, kann das Schema manuell in Startup.Configure festgelegt werden, bevor ein beliebiger Middlewaretyp verwendet wird:

app.Use((context, next) =>
{
    context.Request.Scheme = "https";
    return next();
});

Dieser Code kann mit einer Umgebungsvariablen oder einer anderen Konfigurationseinstellung in einer Entwicklungs- oder Stagingumgebung deaktiviert werden.

Umgang mit Pfadbasis und Proxys, die den Anforderungspfad ändern

Einige Proxys übergeben den Pfad intakt, aber mit einem App-basierten Pfad, der entfernt werden sollte, damit das Routing ordnungsgemäß funktioniert. UsePathBaseExtensions.UsePathBase-Middleware teilt den Pfad in HttpRequest.Path und den App-Basispfad in HttpRequest.PathBase.

Wenn /foo der App-Basispfad für einen als /foo/api/1 übergebenen Proxypfad ist, setzt die Middleware mit dem folgenden Befehl Request.PathBase auf /foo und Request.Path auf /api/1:

app.UsePathBase("/foo");

Der ursprüngliche Pfad und die Pfadbasis werden erneut angewendet, wenn die Middleware in umgekehrter Reihenfolge erneut aufgerufen wird. Weitere Informationen zur Reihenfolge der Middlewareverarbeitung finden Sie unter ASP.NET Core-Middleware.

Wenn der Proxy den Pfad abschneidet (z.B. Weiterleitung von /foo/api/1 zu /api/1), korrigieren Sie Umleitungen und Links, indem Sie die Eigenschaft /foo/api/1 der Anforderungen setzen:

app.Use((context, next) =>
{
    context.Request.PathBase = new PathString("/foo");
    return next();
});

Wenn der Proxy Pfaddaten hinzufügt, verwerfen Sie einen Teil des Pfads, um Umleitungen und Links zu korrigieren, indem Sie StartsWithSegments verwenden und der Path-Eigenschaft zuweisen:

app.Use((context, next) =>
{
    if (context.Request.Path.StartsWithSegments("/foo", out var remainder))
    {
        context.Request.Path = remainder;
    }

    return next();
});

Konfiguration für einen Proxy, der andere Headernamen verwendet

Verwendet der Proxy zum Weiterleiten der Proxyadresse/des Ports und zum Erzeugen der Schemainformationen andere Headernamen als X-Forwarded-For und X-Forwarded-Proto, passen Sie die Optionen ForwardedForHeaderName und ForwardedProtoHeaderName entsprechend an:

services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedForHeaderName = "Header_Name_Used_By_Proxy_For_X-Forwarded-For_Header";
    options.ForwardedProtoHeaderName = "Header_Name_Used_By_Proxy_For_X-Forwarded-Proto_Header";
});

Das Schema für Linux- und Nicht-IIS-Reverseproxys weiterleiten

Apps, die UseHttpsRedirection und UseHsts aufrufen, versetzen eine Site in eine Endlosschleife, falls die Bereitstellung in einem Azure Linux App Service, auf einem virtuellen Azure Linux-Computer, oder hinter einem anderen Reverseproxy als IIS erfolgt. TLS wird vom Reverseproxy beendet, und Kestrel wird nicht auf das richtige Anforderungsschema aufmerksam gemacht. OAuth und OIDC schlagen in dieser Konfiguration ebenfalls fehl, weil sie falsche Umleitungen generieren. UseIISIntegration fügt die Middleware für weitergeleitete Header hinzu und konfiguriert sie, wenn es hinter IIS ausgeführt wird, aber es gibt keine entsprechende automatische Konfiguration für Linux (Apache- oder Nginx-Integration).

Um das Schema von dem Proxy in Nicht-IIS-Szenarios weiterzuleiten, fügen Sie die Middleware für weitergeleitete Header hinzu, und konfigurieren Sie sie. In Startup.ConfigureServices verwenden Sie folgenden Code:

// using Microsoft.AspNetCore.HttpOverrides;

if (string.Equals(
    Environment.GetEnvironmentVariable("ASPNETCORE_FORWARDEDHEADERS_ENABLED"),
    "true", StringComparison.OrdinalIgnoreCase))
{
    services.Configure<ForwardedHeadersOptions>(options =>
    {
        options.ForwardedHeaders = ForwardedHeaders.XForwardedFor |
            ForwardedHeaders.XForwardedProto;
        // Only loopback proxies are allowed by default.
        // Clear that restriction because forwarders are enabled by explicit
        // configuration.
        options.KnownNetworks.Clear();
        options.KnownProxies.Clear();
    });
}

Zertifikatweiterleitung

Azure

Informationen zum Konfigurieren von Azure App Service für die Zertifikatsweiterleitung finden Sie unter Konfigurieren der gegenseitigen TLS-Authentifizierung für Azure App Service. Die folgende Anleitung bezieht sich auf die Konfiguration der ASP.NET Core-App.

Fügen Sie Startup.Configure direkt vor dem Aufruf von app.UseAuthentication(); den folgenden Code hinzu:

app.UseCertificateForwarding();

Konfigurieren Sie die Middleware für die Zertifikatweiterleitung, um den von Azure verwendeten Headernamen anzugeben. Fügen Sie in Startup.ConfigureServices den folgenden Code hinzu, um den Header zu konfigurieren, anhand dessen die Middleware ein Zertifikat erstellt:

services.AddCertificateForwarding(options =>
    options.CertificateHeader = "X-ARR-ClientCert");

Andere Webproxys

Wenn ein Proxy verwendet wird, der nicht IIS oder Routing von Anwendungsanforderungen von Azure App Service entspricht, konfigurieren Sie den Proxy so, dass das empfangene Zertifikat in einem HTTP-Header weitergeleitet wird. Fügen Sie Startup.Configure direkt vor dem Aufruf von app.UseAuthentication(); den folgenden Code hinzu:

app.UseCertificateForwarding();

Konfigurieren Sie die Middleware für die Zertifikatweiterleitung konfigurieren, um den Headernamen anzugeben. Fügen Sie in Startup.ConfigureServices den folgenden Code hinzu, um den Header zu konfigurieren, anhand dessen die Middleware ein Zertifikat erstellt:

services.AddCertificateForwarding(options =>
    options.CertificateHeader = "YOUR_CERTIFICATE_HEADER_NAME");

Wenn der Proxy das Zertifikat mit nicht mit base64 codiert (wie bei Nginx), legen Sie die Option HeaderConverter fest. Betrachten Sie das folgende Beispiel in Startup.ConfigureServices:

services.AddCertificateForwarding(options =>
{
    options.CertificateHeader = "YOUR_CUSTOM_HEADER_NAME";
    options.HeaderConverter = (headerValue) =>
    {
        var clientCertificate =
           /* some conversion logic to create an X509Certificate2 */
        return clientCertificate;
    }
});

Problembehandlung

Wenn Header nicht wie erwartet zugewiesen werden, aktivieren Sie die Protokollierung. Wenn die Protokolle nicht genügend Informationen zur Problembehandlung bereitstellen, listen Sie die vom Server empfangenen Anforderungsheader auf. Verwenden Sie Inlinemiddleware, um Anforderungsheader in eine App-Antwort zu schreiben oder die Header zu protokollieren.

Um die Header in die Antwort der App zu schreiben, platzieren Sie die folgende Terminalinlinemiddleware unmittelbar hinter den Aufruf von UseForwardedHeaders in Startup.Configure:

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}");
});

Statt in den Antworttext können Sie in Protokolle schreiben. Das Schreiben in Protokolle ermöglicht es der Website, während des Debuggens normal zu funktionieren.

So schreiben Sie in Protokolle und nicht in den Antworttext:

• Fügen Sie ILogger<Startup> in die Startup-Klasse ein, wie unter ILogger<Startup> beschrieben.
• Platzieren Sie die folgende Inlinemiddleware unmittelbar hinter den Aufruf von UseForwardedHeaders in Startup.Configure.

app.Use(async (context, next) =>
{
    // Request method, scheme, path, and base path
    _logger.LogDebug("Request Method: {Method}", context.Request.Method);
    _logger.LogDebug("Request Scheme: {Scheme}", context.Request.Scheme);
    _logger.LogDebug("Request Path: {Path}", context.Request.Path);
    _logger.LogDebug("Request Path Base: {PathBase}", context.Request.PathBase);

    // Headers
    foreach (var header in context.Request.Headers)
    {
        _logger.LogDebug("Header: {Key}: {Value}", header.Key, header.Value);
    }

    // Connection: RemoteIp
    _logger.LogDebug("Request RemoteIp: {RemoteIpAddress}",
        context.Connection.RemoteIpAddress);

    await next();
});

Bei der Verarbeitung werden X-Forwarded-{For|Proto|Host|Prefix}-Werte in X-Original-{For|Proto|Host|Prefix} verschoben. Wenn in einem bestimmten Header mehrere Werte vorhanden sind, verarbeitet die Middleware der Weiterleitungsheader die Header in umgekehrter Reihenfolge von rechts nach links. Der Standardwert von ForwardLimit ist 1 (eins), sodass nur der äußere rechte Wert aus den Headern verarbeitet wird, es sei denn, der Wert von ForwardLimit wird erhöht.

Die ursprüngliche IP-Remoteadresse der Anforderung muss mit einem Eintrag in den KnownProxies- oder KnownNetworks-Listen übereinstimmen, bevor weitergeleitete Header verarbeitet werden. Auf diese Weise wird das Headerspoofing begrenzt, da keine Weiterleitungen von nicht vertrauenswürdigen Proxys akzeptiert werden. Wenn ein unbekannter Proxy erkannt wird, gibt die Protokollierung die Adresse des Proxys an:

September 20th 2018, 15:49:44.168 Unknown proxy: 10.0.0.100:54321

Im vorherigen Beispiel ist 10.0.0.100 ein Proxyserver. Wenn der Server ein vertrauenswürdiger Proxy ist, fügen Sie die IP-Adresse des Servers KnownProxies (oder ein vertrauenswürdiges Netzwerk KnownNetworks) in Startup.ConfigureServices hinzu. Weitere Informationen finden Sie im Abschnitt Middleware für weitergeleitete Header: Optionen.

services.Configure<ForwardedHeadersOptions>(options =>
{
    options.KnownProxies.Add(IPAddress.Parse("10.0.0.100"));
});

Zusätzliche Ressourcen

• Hosten von ASP.NET Core in einer Webfarm
• Microsoft Security Advisory CVE-2018-0787: ASP.NET Core Elevation Of Privilege Vulnerability (Microsoft-Sicherheitsempfehlung CVE-2018-0787: Sicherheitsrisiko durch Rechteerweiterungen in ASP.NET Core)
• YARP: Yet Another Reverse Proxy (ein weiterer Reverseproxy)