Konfigurieren von ASP.NET Core zur Verwendung mit Proxyservern und LastenausgleichConfigure ASP.NET Core to work with proxy servers and load balancers

Von Chris RossBy Chris Ross

In der für ASP.NET Core empfohlenen Konfiguration wird die App mit dem IIS/ASP.NET Core-Modul, Nginx oder Apache gehostet.In the recommended configuration for ASP.NET Core, the app is hosted using IIS/ASP.NET Core Module, Nginx, or Apache. Proxyserver, Lastenausgleichsmodule und anderen Netzwerkgeräte verdecken häufig Informationen über die Anforderung, bevor diese die App erreicht:Proxy servers, load balancers, and other network appliances often obscure information about the request before it reaches the app:

  • Wenn HTTPS-Anforderungen über HTTP-Proxy ausgeführt werden, geht das ursprüngliche Schema (HTTPS) verloren und muss in einem Header weitergeleitet werden.When HTTPS requests are proxied over HTTP, the original scheme (HTTPS) is lost and must be forwarded in a header.
  • 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.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.

Diese Informationen können im Anforderungsprozess, z.B. in Umleitungen, bei der Authentifizierung, der Linkgenerierung, der Richtlinienauswertung und der Client-Geolocation wichtig sein.This information may be important in request processing, for example in redirects, authentication, link generation, policy evaluation, and client geolocation.

Weitergeleitete HeaderForwarded headers

Gemäß der Konvention leiten Proxys Informationen in HTTP-Headern weiter.By convention, proxies forward information in HTTP headers.

HeaderHeader BeschreibungDescription
X-Forwarded-ForX-Forwarded-For Enthält Informationen zum Client, der die Anforderung und die nachfolgenden Proxys in einer Kette von Proxys initiiert hat.Holds information about the client that initiated the request and subsequent proxies in a chain of proxies. Dieser Parameter kann IP-Adressen (und optional Portnummern) enthalten.This parameter may contain IP addresses (and, optionally, port numbers). Der erste Parameter in einer Kette von Proxyservern gibt den Client an, auf dem die Anforderung zuerst gesendet wurde.In a chain of proxy servers, the first parameter indicates the client where the request was first made. Darauf folgen weitere Proxybezeichner.Subsequent proxy identifiers follow. Der letzte Proxy in der Kette ist nicht in der Liste der Parameter.The last proxy in the chain isn't in the list of parameters. Die IP-Adresse des letzten Proxys und optional eine Portnummer stehen als Remote IP-Adresse auf der Transportschicht zur Verfügung.The last proxy's IP address, and optionally a port number, are available as the remote IP address at the transport layer.
X-Forwarded-ProtoX-Forwarded-Proto Der Wert des ursprünglichen Schemas (HTTP/HTTPS).The value of the originating scheme (HTTP/HTTPS). Der Wert kann auch eine Liste von Schemas sein, wenn die Anforderung mehrere Proxys durchlaufen hat.The value may also be a list of schemes if the request has traversed multiple proxies.
X-Forwarded-HostX-Forwarded-Host Der ursprüngliche Wert des Felds „Hostheader“.The original value of the Host header field. In der Regel ändern Proxys den Hostheader nicht.Usually, proxies don't modify the Host header. Informationen zu einem Sicherheitsrisiko, das Rechteerweiterungen ermöglicht und sich auf Systeme auswirkt, in denen der Proxy Hostheader nicht validiert oder auf als unbedenklich bekannte Werte beschränkt, finden Sie in der Microsoft-Sicherheitsempfehlung CVE-2018-0787.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 restrict Host headers to known good values.

Die Middleware für weitergeleitete Header aus dem Paket Microsoft.AspNetCore.HttpOverrides liest die Header und füllt die zugehörigen Felder in HttpContext aus.The Forwarded Headers Middleware, from the Microsoft.AspNetCore.HttpOverrides package, reads these headers and fills in the associated fields on HttpContext.

Die Middleware aktualisiert:The middleware updates:

Die Standardeinstellungen der Middleware für weitergeleitete Header können konfiguriert werden.Forwarded Headers Middleware default settings can be configured. Folgende Standardeinstellungen sind verfügbar:The default settings are:

  • Zwischen App und Quelle der Anforderungen ist nur ein Proxy vorhanden.There is only one proxy between the app and the source of the requests.
  • Loopbackadressen sind für bekannte Proxys und bekannte Netzwerke konfiguriert.Only loopback addresses are configured for known proxies and known networks.
  • Die weitergeleiteten Header heißen X-Forwarded-For und X-Forwarded-Proto.The forwarded headers are named X-Forwarded-For and X-Forwarded-Proto.

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.Not all network appliances add the X-Forwarded-For and X-Forwarded-Proto headers without additional configuration. Lesen Sie in der Anleitung des Geräteherstellers nach, wenn über einen Proxy übermittelte Anfragen ohne diese Header in der Anwendung eingehen.Consult your appliance manufacturer's guidance if proxied requests don't contain these headers when they reach the app. Verwendet das Gerät andere Headernamen als X-Forwarded-For und X-Forwarded-Proto, passen Sie die Optionen ForwardedForHeaderName und ForwardedProtoHeaderName entsprechend an.If the appliance uses different header names than X-Forwarded-For and X-Forwarded-Proto, set the ForwardedForHeaderName and ForwardedProtoHeaderName options to match the header names used by the appliance. Weitere Informationen finden Sie in den Abschnitten Middleware für weitergeleitete Header: Optionen und Konfiguration für einen Proxy, der andere Headernamen nutzt.For more information, see Forwarded Headers Middleware options and Configuration for a proxy that uses different header names.

IIS-/IIS Express und ASP.NET Core-ModulIIS/IIS Express and ASP.NET Core Module

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.Forwarded Headers Middleware is enabled by default by IIS Integration Middleware when the app is hosted out-of-process behind IIS and the ASP.NET Core Module. 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).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). 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.The middleware is configured to forward the X-Forwarded-For and X-Forwarded-Proto headers and is restricted to a single localhost proxy. Wenn zusätzliche Konfigurationsschritte erforderlich sind, finden Sie weitere Informationen unter Middleware für weitergeleitete Header: Optionen.If additional configuration is required, see the Forwarded Headers Middleware options.

Andere Proxyserver- und LastenausgleichsszenariosOther proxy server and load balancer scenarios

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.Outside of using IIS Integration when hosting out-of-process, Forwarded Headers Middleware isn't enabled by default. Middleware für weitergeleitete Header muss aktiviert sein, damit eine App weitergeleitete Header mit UseForwardedHeaders verarbeitet.Forwarded Headers Middleware must be enabled for an app to process forwarded headers with UseForwardedHeaders. Sind nach der Aktivierung der Middleware keine ForwardedHeadersOptions für die Middleware angegeben, sind die standardmäßigen ForwardedHeadersOptions.ForwardedHeaders gleich ForwardedHeaders.None.After enabling the middleware if no ForwardedHeadersOptions are specified to the middleware, the default ForwardedHeadersOptions.ForwardedHeaders are ForwardedHeaders.None.

Konfigurieren Sie die Middleware mit ForwardedHeadersOptions so, dass die Header X-Forwarded-For und X-Forwarded-Proto in Startup.ConfigureServices weitergeleitet werden.Configure the middleware with ForwardedHeadersOptions to forward the X-Forwarded-For and X-Forwarded-Proto headers in Startup.ConfigureServices.

Middleware für weitergeleitete Header: AuftragForwarded Headers Middleware order

Die Middleware für weitergeleitete Header muss noch vor einer anderen Middleware ausgeführt werden.Forwarded Headers Middleware should run before other middleware. Mit dieser Reihenfolge wird sichergestellt, dass die auf Informationen von weitergeleiteten Headern basierende Middleware die zu verarbeitenden Headerwerte nutzen kann.This ordering ensures that the middleware relying on forwarded headers information can consume the header values for processing. 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:Forwarded Headers Middleware can run after diagnostics and error handling, but it must be be run before calling UseHsts:

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:Alternatively, call UseForwardedHeaders before diagnostics:

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

Hinweis

Sind keine ForwardedHeadersOptions in Startup.ConfigureServices oder direkt für die Erweiterungsmethode mit UseForwardedHeaders angegeben, sind die weiterzuleitenden Standardheader gleich ForwardedHeaders.None.If no ForwardedHeadersOptions are specified in Startup.ConfigureServices or directly to the extension method with UseForwardedHeaders, the default headers to forward are ForwardedHeaders.None. Die ForwardedHeaders-Eigenschaft muss mit den weiterzuleitenden Headern konfiguriert werden.The ForwardedHeaders property must be configured with the headers to forward.

Nginx-KonfigurationNginx configuration

Informationen zur Weiterleitung der Header X-Forwarded-For und X-Forwarded-Proto finden Sie unter Hosten von ASP.NET Core unter Linux mit Nginx.To forward the X-Forwarded-For and X-Forwarded-Proto headers, see Hosten von ASP.NET Core unter Linux mit Nginx. Weitere Informationen finden Sie unter NGINX: Using the Forwarded header (NGINX: Verwenden des weitergeleiteten Headers).For more information, see NGINX: Using the Forwarded header.

Apache-KonfigurationApache configuration

X-Forwarded-For wird automatisch hinzugefügt (siehe Apache Module mod_proxy: Reverse Proxy Request Headers (Apache-Modul mod_proxy: Anforderungsheader für Reverseproxys)).X-Forwarded-For is added automatically (see Apache Module mod_proxy: Reverse Proxy Request Headers). Informationen zur Weiterleitung des Headers X-Forwarded-Proto finden Sie unter Hosten von ASP.NET Core unter Linux mit Apache.For information on how to forward the X-Forwarded-Proto header, see Hosten von ASP.NET Core unter Linux mit Apache.

Middleware für weitergeleitete Header: OptionenForwarded Headers Middleware options

ForwardedHeadersOptions steuern das Verhalten der Middleware für weitergeleitete Header.ForwardedHeadersOptions control the behavior of the Forwarded Headers Middleware. Im folgenden Beispiel werden die Standardwerte geändert:The following example changes the default values:

  • Beschränken Sie die Zahl der Einträge in den weitergeleiteten Headern auf 2.Limit the number of entries in the forwarded headers to 2.
  • Fügen Sie eine bekannte Proxyadresse von 127.0.10.1 hinzu.Add a known proxy address of 127.0.10.1.
  • Ändern Sie den Namen des weitergeleiteten Headers vom Standardwert X-Forwarded-For in den Wert X-Forwarded-For-My-Custom-Header-Name.Change the forwarded header name from the default X-Forwarded-For to 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";
});
OptionOption BeschreibungDescription
AllowedHosts Begrenzt Hosts durch den X-Forwarded-Host-Header auf die angegebenen Werte.Restricts hosts by the X-Forwarded-Host header to the values provided.
  • Werte werden mit Ordnungszahl/Groß-/Kleinschreibung ignorieren verglichen.Values are compared using ordinal-ignore-case.
  • Portnummern müssen ausgeschlossen werden.Port numbers must be excluded.
  • Wenn die Liste leer ist, sind alle Hosts zulässig.If the list is empty, all hosts are allowed.
  • Ein Platzhalter * auf der obersten Ebene lässt alle nicht leeren Hosts zu.A top-level wildcard * allows all non-empty hosts.
  • Unterdomänen-Platzhalter sind zulässig, stimmen aber nicht mit der Stammdomäne überein.Subdomain wildcards are permitted but don't match the root domain. Beispielsweise entspricht *.contoso.com der Unterdomäne foo.contoso.com, aber nicht der Stammdomäne contoso.com.For example, *.contoso.com matches the subdomain foo.contoso.com but not the root domain contoso.com.
  • Unicode-Hostnamen sind zulässig, werden jedoch für den Abgleich in Punycode konvertiert.Unicode host names are allowed but are converted to Punycode for matching.
  • IPv6-Adressen müssen Begrenzungsklammern einschließen und im konventionellen Format vorliegen (z.B. [ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]).IPv6 addresses must include bounding brackets and be in conventional form (for example, [ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]). IPv6-Adressen sind keine Sonderfälle, um auf logische Gleichheit zwischen verschiedenen Formaten zu prüfen, und es wird keine Kanonisierung durchgeführt.IPv6 addresses aren't special-cased to check for logical equality between different formats, and no canonicalization is performed.
  • Dadurch, dass die zulässigen Hosts nicht begrenzt werden, kann einem Angreifer die Möglichkeit eröffnet werden, von dem Dienst generierte Links zu fälschen.Failure to restrict the allowed hosts may allow an attacker to spoof links generated by the service.
Der Standardwert ist eine leere IList<string>.The default value is an empty IList<string>.
ForwardedForHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XForwardedForHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedForHeaderName. Diese Option wird verwendet, wenn beim Proxy/Weiterleitenden nicht der Header X-Forwarded-For sondern ein anderer Header für die Weiterleitung der Informationen genutzt wird.This option is used when the proxy/forwarder doesn't use the X-Forwarded-For header but uses some other header to forward the information.

Der Standardwert ist X-Forwarded-For.The default is X-Forwarded-For.
ForwardedHeaders Gibt an, welche Weiterleitungen verarbeitet werden sollen.Identifies which forwarders should be processed. Weitere Informationen zur Liste der anzuwendenden Felder finden Sie unter ForwardedHeaders Enum.See the ForwardedHeaders Enum for the list of fields that apply. Typische Werte, die dieser Eigenschaft zugewiesen wurden, sind ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto.Typical values assigned to this property are ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto.

Der Standardwert ist ForwardedHeaders.None.The default value is ForwardedHeaders.None.
ForwardedHostHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XForwardedHostHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedHostHeaderName. Diese Option wird verwendet, wenn beim Proxy/Weiterleitenden nicht der Header X-Forwarded-Host sondern ein anderer Header für die Weiterleitung der Informationen genutzt wird.This option is used when the proxy/forwarder doesn't use the X-Forwarded-Host header but uses some other header to forward the information.

Der Standardwert ist X-Forwarded-Host.The default is X-Forwarded-Host.
ForwardedProtoHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XForwardedProtoHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedProtoHeaderName. Diese Option wird verwendet, wenn beim Proxy/Weiterleitenden nicht der Header X-Forwarded-Proto sondern ein anderer Header für die Weiterleitung der Informationen genutzt wird.This option is used when the proxy/forwarder doesn't use the X-Forwarded-Proto header but uses some other header to forward the information.

Der Standardwert ist X-Forwarded-Proto.The default is X-Forwarded-Proto.
ForwardLimit Schränkt die Anzahl der Einträge in den Headern ein, die verarbeitet werden.Limits the number of entries in the headers that are processed. Legen Sie den Wert null fest, um die Einschränkung zu deaktivieren. Diese Einstellung sollte jedoch nur vorgenommen werden, wenn KnownProxies oder KnownNetworks konfiguriert sind.Set to null to disable the limit, but this should only be done if KnownProxies or KnownNetworks are configured. Das Festlegen eines Werts ungleich null ist eine Vorsichtsmaßnahme (aber keine Garantie) zum Schutz vor falsch konfigurierten Proxys und schädlichen Anforderungen aus Seitenkanälen im Netzwerk.Setting a non-null value is a precaution (but not a guarantee) to guard against misconfigured proxies and malicious requests arriving from side-channels on the network.

Die Middleware der Weiterleitungsheader verarbeitet Header in umgekehrter Reihenfolge von rechts nach links.Forwarded Headers Middleware processes headers in reverse order from right to left. Wenn der Standardwert von (1) verwendet wird, wird nur der äußere rechte Wert aus den Headern verarbeitet, es sei denn, der Wert von ForwardLimit wird erhöht.If the default value (1) is used, only the rightmost value from the headers is processed unless the value of ForwardLimit is increased.

Der Standardwert ist 1.The default is 1.
KnownNetworks Adressbereiche bekannter Netzwerke; von dort weitergeleitete Header müssen akzeptiert werden.Address ranges of known networks to accept forwarded headers from. Geben Sie IP-Adressbereiche mithilfe der CIDR-Notation (Classless Interdomain Routing) an.Provide IP ranges using Classless Interdomain Routing (CIDR) notation.

Wenn der Server Dualmodussockets verwendet, werden IPv4-Adressen in einem IPv6-Format bereitgestellt (z.B. wird 10.0.0.1 in IPv4 in IPv6 als ::ffff:10.0.0.1 dargestellt).If the server is using dual-mode sockets, IPv4 addresses are supplied in an IPv6 format (for example, 10.0.0.1 in IPv4 represented in IPv6 as ::ffff:10.0.0.1). Siehe IPAddress.MapToIPv6.See IPAddress.MapToIPv6. Bestimmen Sie mithilfe der HttpContext.Connection.RemoteIpAddress, ob dieses Format erforderlich ist.Determine if this format is required by looking at the HttpContext.Connection.RemoteIpAddress. Weitere Informationen finden Sie im Abschnitt Konfiguration für eine IPv4-Adresse, die als IPv6-Adresse dargestellt wird.For more information, see the Configuration for an IPv4 address represented as an IPv6 address section.

Der Standardwert ist IList<IPNetwork> mit einem Eintrag für IPAddress.Loopback.The default is an IList<IPNetwork> containing a single entry for IPAddress.Loopback.
KnownProxies Adressen bekannter Proxys, von denen weitergeleitete Header akzeptiert werden müssen.Addresses of known proxies to accept forwarded headers from. Verwenden Sie KnownProxies, um genaue IP-Adressübereinstimmungen anzugeben.Use KnownProxies to specify exact IP address matches.

Wenn der Server Dualmodussockets verwendet, werden IPv4-Adressen in einem IPv6-Format bereitgestellt (z.B. wird 10.0.0.1 in IPv4 in IPv6 als ::ffff:10.0.0.1 dargestellt).If the server is using dual-mode sockets, IPv4 addresses are supplied in an IPv6 format (for example, 10.0.0.1 in IPv4 represented in IPv6 as ::ffff:10.0.0.1). Siehe IPAddress.MapToIPv6.See IPAddress.MapToIPv6. Bestimmen Sie mithilfe der HttpContext.Connection.RemoteIpAddress, ob dieses Format erforderlich ist.Determine if this format is required by looking at the HttpContext.Connection.RemoteIpAddress. Weitere Informationen finden Sie im Abschnitt Konfiguration für eine IPv4-Adresse, die als IPv6-Adresse dargestellt wird.For more information, see the Configuration for an IPv4 address represented as an IPv6 address section.

Der Standardwert ist IList<IPAddress> mit einem Eintrag für IPAddress.IPv6Loopback.The default is an IList<IPAddress> containing a single entry for IPAddress.IPv6Loopback.
OriginalForHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XOriginalForHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalForHeaderName.

Der Standardwert ist X-Original-For.The default is X-Original-For.
OriginalHostHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XOriginalHostHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalHostHeaderName.

Der Standardwert ist X-Original-Host.The default is X-Original-Host.
OriginalProtoHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XOriginalProtoHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalProtoHeaderName.

Der Standardwert ist X-Original-Proto.The default is X-Original-Proto.
RequireHeaderSymmetry Die Anzahl von Headerwerten muss in den ForwardedHeadersOptions.ForwardedHeaders übereinstimmen, die verarbeitet werden.Require the number of header values to be in sync between the ForwardedHeadersOptions.ForwardedHeaders being processed.

Die Standardeinstellung in ASP.NET Core 1.x ist true.The default in ASP.NET Core 1.x is true. Die Standardeinstellung in ASP.NET Core 2.0 oder höher ist false.The default in ASP.NET Core 2.0 or later is false.

Szenarios und AnwendungsfälleScenarios and use cases

Wenn keine weitergeleiteten Header hinzugefügt werden können und alle Anforderungen sicher sindWhen it isn't possible to add forwarded headers and all requests are secure

In einigen Fällen ist es möglicherweise ausgeschlossen, weitergeleitete Header den Anforderungen hinzuzufügen, die über einen Proxy an die App übermittelt werden.In some cases, it might not be possible to add forwarded headers to the requests proxied to the app. 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: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();
});

Dieser Code kann mit einer Umgebungsvariablen oder einer anderen Konfigurationseinstellung in einer Entwicklungs- oder Stagingumgebung deaktiviert werden.This code can be disabled with an environment variable or other configuration setting in a development or staging environment.

Umgang mit Pfadbasis und Proxys, die den Anforderungspfad ändernDeal with path base and proxies that change the request path

Einige Proxys übergeben den Pfad intakt, aber mit einem App-basierten Pfad, der entfernt werden sollte, damit das Routing ordnungsgemäß funktioniert.Some proxies pass the path intact but with an app base path that should be removed so that routing works properly. UsePathBaseExtensions.UsePathBase-Middleware teilt den Pfad in HttpRequest.Path und den App-Basispfad in HttpRequest.PathBase.UsePathBaseExtensions.UsePathBase middleware splits the path into HttpRequest.Path and the app base path into 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: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");

Der ursprüngliche Pfad und die Pfadbasis werden erneut angewendet, wenn die Middleware in umgekehrter Reihenfolge erneut aufgerufen wird.The original path and path base are reapplied when the middleware is called again in reverse. Weitere Informationen zur Verarbeitungsreihenfolge in der Middleware finden Sie unter ASP.NET Core-Middleware.For more information on middleware order processing, see 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 PathBase der Anforderungen setzen: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();
});

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:If the proxy is adding path data, discard part of the path to fix redirects and links by using StartsWithSegments 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();
});

Konfiguration für einen Proxy, der andere Headernamen verwendetConfiguration for a proxy that uses different header names

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:If the proxy doesn't use headers named X-Forwarded-For and X-Forwarded-Proto to forward the proxy address/port and originating scheme information, set the ForwardedForHeaderName and ForwardedProtoHeaderName options to match the header names used by the proxy:

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

Konfiguration für eine IPv4-Adresse, die als IPv6-Adresse dargestellt wirdConfiguration for an IPv4 address represented as an IPv6 address

Wenn der Server Dualmodussockets verwendet, werden IPv4-Adressen in einem IPv6-Format bereitgestellt (z.B. wird 10.0.0.1 in IPv4 in IPv6 als ::ffff:10.0.0.1 oder ::ffff:a00:1 dargestellt).If the server is using dual-mode sockets, IPv4 addresses are supplied in an IPv6 format (for example, 10.0.0.1 in IPv4 represented in IPv6 as ::ffff:10.0.0.1 or ::ffff:a00:1). Siehe IPAddress.MapToIPv6.See IPAddress.MapToIPv6. Bestimmen Sie mithilfe der HttpContext.Connection.RemoteIpAddress, ob dieses Format erforderlich ist.Determine if this format is required by looking at the HttpContext.Connection.RemoteIpAddress.

Im folgenden Beispiel wird eine Netzwerkadresse, die weitergeleitete Header bereitstellt, der KnownNetworks-Liste im IPv6-Format hinzugefügt.In the following example, a network address that supplies forwarded headers is added to the KnownNetworks list in IPv6 format.

IPv4-Adresse: 10.11.12.1/8IPv4 address: 10.11.12.1/8

Konvertierte IPv6-Adresse: ::ffff:10.11.12.1Converted IPv6 address: ::ffff:10.11.12.1
Konvertierte Präfixlänge: 104Converted prefix length: 104

Sie können die Adresse auch im Hexadezimalformat angeben (10.11.12.1 in IPv6 als ::ffff:0a0b:0c01 dargestellt).You can also supply the address in hexadecimal format (10.11.12.1 represented in IPv6 as ::ffff:0a0b:0c01). Fügen Sie bei der Konvertierung einer IPv4-Adresse in IPv6 der CIDR-Präfixlänge 96 (8 im Beispiel) für das zusätzliche ::ffff:-IPv6-Präfix hinzu (8 + 96 = 104).When converting an IPv4 address to IPv6, add 96 to the CIDR Prefix Length (8 in the example) to account for the additional ::ffff: IPv6 prefix (8 + 96 = 104).

// To access IPNetwork and IPAddress, add the following namespaces:
// using using System.Net;
// using Microsoft.AspNetCore.HttpOverrides;
services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    options.KnownNetworks.Add(new IPNetwork(
        IPAddress.Parse("::ffff:10.11.12.1"), 104));
});

Das Schema für Linux- und Nicht-IIS-Reverseproxys weiterleitenForward the scheme for Linux and non-IIS reverse proxies

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.Apps that call UseHttpsRedirection and UseHsts put a site into an infinite loop if deployed to an Azure Linux App Service, Azure Linux virtual machine (VM), or behind any other reverse proxy besides IIS. TLS wird vom Reverseproxy beendet, und Kestrel wird nicht auf das richtige Anforderungsschema aufmerksam gemacht.TLS is terminated by the reverse proxy, and Kestrel isn't made aware of the correct request scheme. OAuth und OIDC schlagen in dieser Konfiguration ebenfalls fehl, weil sie falsche Umleitungen generieren.OAuth and OIDC also fail in this configuration because they generate incorrect redirects. 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).UseIISIntegration adds and configures Forwarded Headers Middleware when running behind IIS, but there's no matching automatic configuration for Linux (Apache or 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.To forward the scheme from the proxy in non-IIS scenarios, add and configure Forwarded Headers Middleware. In Startup.ConfigureServices verwenden Sie folgenden Code:In Startup.ConfigureServices, use the following 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();
    });
}

ZertifikatweiterleitungCertificate forwarding

AzureAzure

Informationen zum Konfigurieren von Azure App Service für die Zertifikatsweiterleitung finden Sie unter Konfigurieren der gegenseitigen TLS-Authentifizierung für Azure App Service.To configure Azure App Service for certificate forwarding, see Configure TLS mutual authentication for Azure App Service. Die folgende Anleitung bezieht sich auf die Konfiguration der ASP.NET Core-App.The following guidance pertains to configuring the ASP.NET Core app.

Fügen Sie Startup.Configure direkt vor dem Aufruf von app.UseAuthentication(); den folgenden Code hinzu:In Startup.Configure, add the following code before the call to app.UseAuthentication();:

app.UseCertificateForwarding();

Konfigurieren Sie die Middleware für die Zertifikatweiterleitung, um den von Azure verwendeten Headernamen anzugeben.Configure Certificate Forwarding Middleware to specify the header name that Azure uses. Fügen Sie in Startup.ConfigureServices den folgenden Code hinzu, um den Header zu konfigurieren, anhand dessen die Middleware ein Zertifikat erstellt:In Startup.ConfigureServices, add the following code to configure the header from which the middleware builds a certificate:

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

Andere WebproxysOther web proxies

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.If a proxy is used that isn't IIS or Azure App Service's Application Request Routing (ARR), configure the proxy to forward the certificate that it received in an HTTP header. Fügen Sie Startup.Configure direkt vor dem Aufruf von app.UseAuthentication(); den folgenden Code hinzu:In Startup.Configure, add the following code before the call to app.UseAuthentication();:

app.UseCertificateForwarding();

Konfigurieren Sie die Middleware für die Zertifikatweiterleitung konfigurieren, um den Headernamen anzugeben.Configure the Certificate Forwarding Middleware to specify the header name. Fügen Sie in Startup.ConfigureServices den folgenden Code hinzu, um den Header zu konfigurieren, anhand dessen die Middleware ein Zertifikat erstellt:In Startup.ConfigureServices, add the following code to configure the header from which the middleware builds a certificate:

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.If the proxy isn't base64-encoding the certificate (as is the case with Nginx), set the HeaderConverter option. Betrachten Sie das folgende Beispiel in Startup.ConfigureServices:Consider the following example 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;
    }
});

ProblembehandlungTroubleshoot

Wenn Header nicht wie erwartet zugewiesen werden, aktivieren Sie die Protokollierung.When headers aren't forwarded as expected, enable logging. Wenn die Protokolle nicht genügend Informationen zur Problembehandlung bereitstellen, listen Sie die vom Server empfangenen Anforderungsheader auf.If the logs don't provide sufficient information to troubleshoot the problem, enumerate the request headers received by the server. Verwenden Sie Inlinemiddleware, um Anforderungsheader in eine App-Antwort zu schreiben oder die Header zu protokollieren.Use inline middleware to write request headers to an app response or log the headers.

Um die Header in die Antwort der App zu schreiben, platzieren Sie die folgende Terminalinlinemiddleware unmittelbar hinter den Aufruf von UseForwardedHeaders in Startup.Configure:To write the headers to the app's response, place the following terminal inline middleware immediately after the call to 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.You can write to logs instead of the response body. Das Schreiben in Protokolle ermöglicht es der Website, während des Debuggens normal zu funktionieren.Writing to logs allows the site to function normally while debugging.

So schreiben Sie in Protokolle und nicht in den Antworttext:To write logs rather than to the response body:

app.Use(async (context, next) =>
{
    // Request method, scheme, and 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);

    // 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}-Werte in X-Original-{For|Proto|Host} verschoben.When processed, X-Forwarded-{For|Proto|Host} values are moved to X-Original-{For|Proto|Host}. Wenn in einem bestimmten Header mehrere Werte vorhanden sind, verarbeitet die Middleware der Weiterleitungsheader die Header in umgekehrter Reihenfolge von rechts nach links.If there are multiple values in a given header, Forwarded Headers Middleware processes headers in reverse order from right to left. 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.The default ForwardLimit is 1 (one), so only the rightmost value from the headers is processed unless the value of ForwardLimit is increased.

Die ursprüngliche IP-Remoteadresse der Anforderung muss mit einem Eintrag in den KnownProxies- oder KnownNetworks-Listen übereinstimmen, bevor weitergeleitete Header verarbeitet werden.The request's original remote IP must match an entry in the KnownProxies or KnownNetworks lists before forwarded headers are processed. Auf diese Weise wird das Headerspoofing begrenzt, da keine Weiterleitungen von nicht vertrauenswürdigen Proxys akzeptiert werden.This limits header spoofing by not accepting forwarders from untrusted proxies. Wenn ein unbekannter Proxy erkannt wird, gibt die Protokollierung die Adresse des Proxys an:When an unknown proxy is detected, logging indicates the address of the proxy:

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

Im vorherigen Beispiel ist 10.0.0.100 ein Proxyserver.In the preceding example, 10.0.0.100 is a proxy server. 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.If the server is a trusted proxy, add the server's IP address to KnownProxies (or add a trusted network to KnownNetworks) in Startup.ConfigureServices. Weitere Informationen finden Sie im Abschnitt Middleware für weitergeleitete Header: Optionen.For more information, see the Forwarded Headers Middleware options section.

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

Wichtig

Erlauben Sie nur vertrauenswürdigen Proxys und Netzwerken die Weiterleitung von Headern.Only allow trusted proxies and networks to forward headers. Andernfalls sind Angriffe des Typs IP-Spoofing möglich.Otherwise, IP spoofing attacks are possible.

Zusätzliche RessourcenAdditional resources

In der für ASP.NET Core empfohlenen Konfiguration wird die App mit dem IIS/ASP.NET Core-Modul, Nginx oder Apache gehostet.In the recommended configuration for ASP.NET Core, the app is hosted using IIS/ASP.NET Core Module, Nginx, or Apache. Proxyserver, Lastenausgleichsmodule und anderen Netzwerkgeräte verdecken häufig Informationen über die Anforderung, bevor diese die App erreicht:Proxy servers, load balancers, and other network appliances often obscure information about the request before it reaches the app:

  • Wenn HTTPS-Anforderungen über HTTP-Proxy ausgeführt werden, geht das ursprüngliche Schema (HTTPS) verloren und muss in einem Header weitergeleitet werden.When HTTPS requests are proxied over HTTP, the original scheme (HTTPS) is lost and must be forwarded in a header.
  • 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.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.

Diese Informationen können im Anforderungsprozess, z.B. in Umleitungen, bei der Authentifizierung, der Linkgenerierung, der Richtlinienauswertung und der Client-Geolocation wichtig sein.This information may be important in request processing, for example in redirects, authentication, link generation, policy evaluation, and client geolocation.

Weitergeleitete HeaderForwarded headers

Gemäß der Konvention leiten Proxys Informationen in HTTP-Headern weiter.By convention, proxies forward information in HTTP headers.

HeaderHeader BeschreibungDescription
X-Forwarded-ForX-Forwarded-For Enthält Informationen zum Client, der die Anforderung und die nachfolgenden Proxys in einer Kette von Proxys initiiert hat.Holds information about the client that initiated the request and subsequent proxies in a chain of proxies. Dieser Parameter kann IP-Adressen (und optional Portnummern) enthalten.This parameter may contain IP addresses (and, optionally, port numbers). Der erste Parameter in einer Kette von Proxyservern gibt den Client an, auf dem die Anforderung zuerst gesendet wurde.In a chain of proxy servers, the first parameter indicates the client where the request was first made. Darauf folgen weitere Proxybezeichner.Subsequent proxy identifiers follow. Der letzte Proxy in der Kette ist nicht in der Liste der Parameter.The last proxy in the chain isn't in the list of parameters. Die IP-Adresse des letzten Proxys und optional eine Portnummer stehen als Remote IP-Adresse auf der Transportschicht zur Verfügung.The last proxy's IP address, and optionally a port number, are available as the remote IP address at the transport layer.
X-Forwarded-ProtoX-Forwarded-Proto Der Wert des ursprünglichen Schemas (HTTP/HTTPS).The value of the originating scheme (HTTP/HTTPS). Der Wert kann auch eine Liste von Schemas sein, wenn die Anforderung mehrere Proxys durchlaufen hat.The value may also be a list of schemes if the request has traversed multiple proxies.
X-Forwarded-HostX-Forwarded-Host Der ursprüngliche Wert des Felds „Hostheader“.The original value of the Host header field. In der Regel ändern Proxys den Hostheader nicht.Usually, proxies don't modify the Host header. Informationen zu einem Sicherheitsrisiko, das Rechteerweiterungen ermöglicht und sich auf Systeme auswirkt, in denen der Proxy Hostheader nicht validiert oder auf als unbedenklich bekannte Werte beschränkt, finden Sie in der Microsoft-Sicherheitsempfehlung CVE-2018-0787.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 restrict Host headers to known good values.

Die Middleware für weitergeleitete Header aus dem Paket Microsoft.AspNetCore.HttpOverrides liest die Header und füllt die zugehörigen Felder in HttpContext aus.The Forwarded Headers Middleware, from the Microsoft.AspNetCore.HttpOverrides package, reads these headers and fills in the associated fields on HttpContext.

Die Middleware aktualisiert:The middleware updates:

Die Standardeinstellungen der Middleware für weitergeleitete Header können konfiguriert werden.Forwarded Headers Middleware default settings can be configured. Folgende Standardeinstellungen sind verfügbar:The default settings are:

  • Zwischen App und Quelle der Anforderungen ist nur ein Proxy vorhanden.There is only one proxy between the app and the source of the requests.
  • Loopbackadressen sind für bekannte Proxys und bekannte Netzwerke konfiguriert.Only loopback addresses are configured for known proxies and known networks.
  • Die weitergeleiteten Header heißen X-Forwarded-For und X-Forwarded-Proto.The forwarded headers are named X-Forwarded-For and X-Forwarded-Proto.

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.Not all network appliances add the X-Forwarded-For and X-Forwarded-Proto headers without additional configuration. Lesen Sie in der Anleitung des Geräteherstellers nach, wenn über einen Proxy übermittelte Anfragen ohne diese Header in der Anwendung eingehen.Consult your appliance manufacturer's guidance if proxied requests don't contain these headers when they reach the app. Verwendet das Gerät andere Headernamen als X-Forwarded-For und X-Forwarded-Proto, passen Sie die Optionen ForwardedForHeaderName und ForwardedProtoHeaderName entsprechend an.If the appliance uses different header names than X-Forwarded-For and X-Forwarded-Proto, set the ForwardedForHeaderName and ForwardedProtoHeaderName options to match the header names used by the appliance. Weitere Informationen finden Sie in den Abschnitten Middleware für weitergeleitete Header: Optionen und Konfiguration für einen Proxy, der andere Headernamen nutzt.For more information, see Forwarded Headers Middleware options and Configuration for a proxy that uses different header names.

IIS-/IIS Express und ASP.NET Core-ModulIIS/IIS Express and ASP.NET Core Module

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.Forwarded Headers Middleware is enabled by default by IIS Integration Middleware when the app is hosted out-of-process behind IIS and the ASP.NET Core Module. 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).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). 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.The middleware is configured to forward the X-Forwarded-For and X-Forwarded-Proto headers and is restricted to a single localhost proxy. Wenn zusätzliche Konfigurationsschritte erforderlich sind, finden Sie weitere Informationen unter Middleware für weitergeleitete Header: Optionen.If additional configuration is required, see the Forwarded Headers Middleware options.

Andere Proxyserver- und LastenausgleichsszenariosOther proxy server and load balancer scenarios

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.Outside of using IIS Integration when hosting out-of-process, Forwarded Headers Middleware isn't enabled by default. Middleware für weitergeleitete Header muss aktiviert sein, damit eine App weitergeleitete Header mit UseForwardedHeaders verarbeitet.Forwarded Headers Middleware must be enabled for an app to process forwarded headers with UseForwardedHeaders. Sind nach der Aktivierung der Middleware keine ForwardedHeadersOptions für die Middleware angegeben, sind die standardmäßigen ForwardedHeadersOptions.ForwardedHeaders gleich ForwardedHeaders.None.After enabling the middleware if no ForwardedHeadersOptions are specified to the middleware, the default ForwardedHeadersOptions.ForwardedHeaders are ForwardedHeaders.None.

Konfigurieren Sie die Middleware mit ForwardedHeadersOptions so, dass die Header X-Forwarded-For und X-Forwarded-Proto in Startup.ConfigureServices weitergeleitet werden.Configure the middleware with ForwardedHeadersOptions to forward the X-Forwarded-For and X-Forwarded-Proto headers in Startup.ConfigureServices. Rufen Sie die Methode UseForwardedHeaders in Startup.Configure auf, bevor Sie andere Middleware aufrufen: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();
}

Hinweis

Sind keine ForwardedHeadersOptions in Startup.ConfigureServices oder direkt für die Erweiterungsmethode mit UseForwardedHeaders angegeben, sind die weiterzuleitenden Standardheader gleich ForwardedHeaders.None.If no ForwardedHeadersOptions are specified in Startup.ConfigureServices or directly to the extension method with UseForwardedHeaders, the default headers to forward are ForwardedHeaders.None. Die ForwardedHeaders-Eigenschaft muss mit den weiterzuleitenden Headern konfiguriert werden.The ForwardedHeaders property must be configured with the headers to forward.

Nginx-KonfigurationNginx configuration

Informationen zur Weiterleitung der Header X-Forwarded-For und X-Forwarded-Proto finden Sie unter Hosten von ASP.NET Core unter Linux mit Nginx.To forward the X-Forwarded-For and X-Forwarded-Proto headers, see Hosten von ASP.NET Core unter Linux mit Nginx. Weitere Informationen finden Sie unter NGINX: Using the Forwarded header (NGINX: Verwenden des weitergeleiteten Headers).For more information, see NGINX: Using the Forwarded header.

Apache-KonfigurationApache configuration

X-Forwarded-For wird automatisch hinzugefügt (siehe Apache Module mod_proxy: Reverse Proxy Request Headers (Apache-Modul mod_proxy: Anforderungsheader für Reverseproxys)).X-Forwarded-For is added automatically (see Apache Module mod_proxy: Reverse Proxy Request Headers). Informationen zur Weiterleitung des Headers X-Forwarded-Proto finden Sie unter Hosten von ASP.NET Core unter Linux mit Apache.For information on how to forward the X-Forwarded-Proto header, see Hosten von ASP.NET Core unter Linux mit Apache.

Middleware für weitergeleitete Header: OptionenForwarded Headers Middleware options

ForwardedHeadersOptions steuern das Verhalten der Middleware für weitergeleitete Header.ForwardedHeadersOptions control the behavior of the Forwarded Headers Middleware. Im folgenden Beispiel werden die Standardwerte geändert:The following example changes the default values:

  • Beschränken Sie die Zahl der Einträge in den weitergeleiteten Headern auf 2.Limit the number of entries in the forwarded headers to 2.
  • Fügen Sie eine bekannte Proxyadresse von 127.0.10.1 hinzu.Add a known proxy address of 127.0.10.1.
  • Ändern Sie den Namen des weitergeleiteten Headers vom Standardwert X-Forwarded-For in den Wert X-Forwarded-For-My-Custom-Header-Name.Change the forwarded header name from the default X-Forwarded-For to 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";
});
OptionOption BeschreibungDescription
AllowedHosts Begrenzt Hosts durch den X-Forwarded-Host-Header auf die angegebenen Werte.Restricts hosts by the X-Forwarded-Host header to the values provided.
  • Werte werden mit Ordnungszahl/Groß-/Kleinschreibung ignorieren verglichen.Values are compared using ordinal-ignore-case.
  • Portnummern müssen ausgeschlossen werden.Port numbers must be excluded.
  • Wenn die Liste leer ist, sind alle Hosts zulässig.If the list is empty, all hosts are allowed.
  • Ein Platzhalter * auf der obersten Ebene lässt alle nicht leeren Hosts zu.A top-level wildcard * allows all non-empty hosts.
  • Unterdomänen-Platzhalter sind zulässig, stimmen aber nicht mit der Stammdomäne überein.Subdomain wildcards are permitted but don't match the root domain. Beispielsweise entspricht *.contoso.com der Unterdomäne foo.contoso.com, aber nicht der Stammdomäne contoso.com.For example, *.contoso.com matches the subdomain foo.contoso.com but not the root domain contoso.com.
  • Unicode-Hostnamen sind zulässig, werden jedoch für den Abgleich in Punycode konvertiert.Unicode host names are allowed but are converted to Punycode for matching.
  • IPv6-Adressen müssen Begrenzungsklammern einschließen und im konventionellen Format vorliegen (z.B. [ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]).IPv6 addresses must include bounding brackets and be in conventional form (for example, [ABCD:EF01:2345:6789:ABCD:EF01:2345:6789]). IPv6-Adressen sind keine Sonderfälle, um auf logische Gleichheit zwischen verschiedenen Formaten zu prüfen, und es wird keine Kanonisierung durchgeführt.IPv6 addresses aren't special-cased to check for logical equality between different formats, and no canonicalization is performed.
  • Dadurch, dass die zulässigen Hosts nicht begrenzt werden, kann einem Angreifer die Möglichkeit eröffnet werden, von dem Dienst generierte Links zu fälschen.Failure to restrict the allowed hosts may allow an attacker to spoof links generated by the service.
Der Standardwert ist eine leere IList<string>.The default value is an empty IList<string>.
ForwardedForHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XForwardedForHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedForHeaderName. Diese Option wird verwendet, wenn beim Proxy/Weiterleitenden nicht der Header X-Forwarded-For sondern ein anderer Header für die Weiterleitung der Informationen genutzt wird.This option is used when the proxy/forwarder doesn't use the X-Forwarded-For header but uses some other header to forward the information.

Der Standardwert ist X-Forwarded-For.The default is X-Forwarded-For.
ForwardedHeaders Gibt an, welche Weiterleitungen verarbeitet werden sollen.Identifies which forwarders should be processed. Weitere Informationen zur Liste der anzuwendenden Felder finden Sie unter ForwardedHeaders Enum.See the ForwardedHeaders Enum for the list of fields that apply. Typische Werte, die dieser Eigenschaft zugewiesen wurden, sind ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto.Typical values assigned to this property are ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto.

Der Standardwert ist ForwardedHeaders.None.The default value is ForwardedHeaders.None.
ForwardedHostHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XForwardedHostHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedHostHeaderName. Diese Option wird verwendet, wenn beim Proxy/Weiterleitenden nicht der Header X-Forwarded-Host sondern ein anderer Header für die Weiterleitung der Informationen genutzt wird.This option is used when the proxy/forwarder doesn't use the X-Forwarded-Host header but uses some other header to forward the information.

Der Standardwert ist X-Forwarded-Host.The default is X-Forwarded-Host.
ForwardedProtoHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XForwardedProtoHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XForwardedProtoHeaderName. Diese Option wird verwendet, wenn beim Proxy/Weiterleitenden nicht der Header X-Forwarded-Proto sondern ein anderer Header für die Weiterleitung der Informationen genutzt wird.This option is used when the proxy/forwarder doesn't use the X-Forwarded-Proto header but uses some other header to forward the information.

Der Standardwert ist X-Forwarded-Proto.The default is X-Forwarded-Proto.
ForwardLimit Schränkt die Anzahl der Einträge in den Headern ein, die verarbeitet werden.Limits the number of entries in the headers that are processed. Legen Sie den Wert null fest, um die Einschränkung zu deaktivieren. Diese Einstellung sollte jedoch nur vorgenommen werden, wenn KnownProxies oder KnownNetworks konfiguriert sind.Set to null to disable the limit, but this should only be done if KnownProxies or KnownNetworks are configured. Das Festlegen eines Werts ungleich null ist eine Vorsichtsmaßnahme (aber keine Garantie) zum Schutz vor falsch konfigurierten Proxys und schädlichen Anforderungen aus Seitenkanälen im Netzwerk.Setting a non-null value is a precaution (but not a guarantee) to guard against misconfigured proxies and malicious requests arriving from side-channels on the network.

Die Middleware der Weiterleitungsheader verarbeitet Header in umgekehrter Reihenfolge von rechts nach links.Forwarded Headers Middleware processes headers in reverse order from right to left. Wenn der Standardwert von (1) verwendet wird, wird nur der äußere rechte Wert aus den Headern verarbeitet, es sei denn, der Wert von ForwardLimit wird erhöht.If the default value (1) is used, only the rightmost value from the headers is processed unless the value of ForwardLimit is increased.

Der Standardwert ist 1.The default is 1.
KnownNetworks Adressbereiche bekannter Netzwerke; von dort weitergeleitete Header müssen akzeptiert werden.Address ranges of known networks to accept forwarded headers from. Geben Sie IP-Adressbereiche mithilfe der CIDR-Notation (Classless Interdomain Routing) an.Provide IP ranges using Classless Interdomain Routing (CIDR) notation.

Wenn der Server Dualmodussockets verwendet, werden IPv4-Adressen in einem IPv6-Format bereitgestellt (z.B. wird 10.0.0.1 in IPv4 in IPv6 als ::ffff:10.0.0.1 dargestellt).If the server is using dual-mode sockets, IPv4 addresses are supplied in an IPv6 format (for example, 10.0.0.1 in IPv4 represented in IPv6 as ::ffff:10.0.0.1). Siehe IPAddress.MapToIPv6.See IPAddress.MapToIPv6. Bestimmen Sie mithilfe der HttpContext.Connection.RemoteIpAddress, ob dieses Format erforderlich ist.Determine if this format is required by looking at the HttpContext.Connection.RemoteIpAddress. Weitere Informationen finden Sie im Abschnitt Konfiguration für eine IPv4-Adresse, die als IPv6-Adresse dargestellt wird.For more information, see the Configuration for an IPv4 address represented as an IPv6 address section.

Der Standardwert ist IList<IPNetwork> mit einem Eintrag für IPAddress.Loopback.The default is an IList<IPNetwork> containing a single entry for IPAddress.Loopback.
KnownProxies Adressen bekannter Proxys, von denen weitergeleitete Header akzeptiert werden müssen.Addresses of known proxies to accept forwarded headers from. Verwenden Sie KnownProxies, um genaue IP-Adressübereinstimmungen anzugeben.Use KnownProxies to specify exact IP address matches.

Wenn der Server Dualmodussockets verwendet, werden IPv4-Adressen in einem IPv6-Format bereitgestellt (z.B. wird 10.0.0.1 in IPv4 in IPv6 als ::ffff:10.0.0.1 dargestellt).If the server is using dual-mode sockets, IPv4 addresses are supplied in an IPv6 format (for example, 10.0.0.1 in IPv4 represented in IPv6 as ::ffff:10.0.0.1). Siehe IPAddress.MapToIPv6.See IPAddress.MapToIPv6. Bestimmen Sie mithilfe der HttpContext.Connection.RemoteIpAddress, ob dieses Format erforderlich ist.Determine if this format is required by looking at the HttpContext.Connection.RemoteIpAddress. Weitere Informationen finden Sie im Abschnitt Konfiguration für eine IPv4-Adresse, die als IPv6-Adresse dargestellt wird.For more information, see the Configuration for an IPv4 address represented as an IPv6 address section.

Der Standardwert ist IList<IPAddress> mit einem Eintrag für IPAddress.IPv6Loopback.The default is an IList<IPAddress> containing a single entry for IPAddress.IPv6Loopback.
OriginalForHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XOriginalForHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalForHeaderName.

Der Standardwert ist X-Original-For.The default is X-Original-For.
OriginalHostHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XOriginalHostHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalHostHeaderName.

Der Standardwert ist X-Original-Host.The default is X-Original-Host.
OriginalProtoHeaderName Verwenden Sie den Header, der von dieser Eigenschaft angegeben wurde, anstelle des von ForwardedHeadersDefaults.XOriginalProtoHeaderName angegebenen.Use the header specified by this property instead of the one specified by ForwardedHeadersDefaults.XOriginalProtoHeaderName.

Der Standardwert ist X-Original-Proto.The default is X-Original-Proto.
RequireHeaderSymmetry Die Anzahl von Headerwerten muss in den ForwardedHeadersOptions.ForwardedHeaders übereinstimmen, die verarbeitet werden.Require the number of header values to be in sync between the ForwardedHeadersOptions.ForwardedHeaders being processed.

Die Standardeinstellung in ASP.NET Core 1.x ist true.The default in ASP.NET Core 1.x is true. Die Standardeinstellung in ASP.NET Core 2.0 oder höher ist false.The default in ASP.NET Core 2.0 or later is false.

Szenarios und AnwendungsfälleScenarios and use cases

Wenn keine weitergeleiteten Header hinzugefügt werden können und alle Anforderungen sicher sindWhen it isn't possible to add forwarded headers and all requests are secure

In einigen Fällen ist es möglicherweise ausgeschlossen, weitergeleitete Header den Anforderungen hinzuzufügen, die über einen Proxy an die App übermittelt werden.In some cases, it might not be possible to add forwarded headers to the requests proxied to the app. 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: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();
});

Dieser Code kann mit einer Umgebungsvariablen oder einer anderen Konfigurationseinstellung in einer Entwicklungs- oder Stagingumgebung deaktiviert werden.This code can be disabled with an environment variable or other configuration setting in a development or staging environment.

Umgang mit Pfadbasis und Proxys, die den Anforderungspfad ändernDeal with path base and proxies that change the request path

Einige Proxys übergeben den Pfad intakt, aber mit einem App-basierten Pfad, der entfernt werden sollte, damit das Routing ordnungsgemäß funktioniert.Some proxies pass the path intact but with an app base path that should be removed so that routing works properly. UsePathBaseExtensions.UsePathBase-Middleware teilt den Pfad in HttpRequest.Path und den App-Basispfad in HttpRequest.PathBase.UsePathBaseExtensions.UsePathBase middleware splits the path into HttpRequest.Path and the app base path into 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: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");

Der ursprüngliche Pfad und die Pfadbasis werden erneut angewendet, wenn die Middleware in umgekehrter Reihenfolge erneut aufgerufen wird.The original path and path base are reapplied when the middleware is called again in reverse. Weitere Informationen zur Verarbeitungsreihenfolge in der Middleware finden Sie unter ASP.NET Core-Middleware.For more information on middleware order processing, see 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 PathBase der Anforderungen setzen: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();
});

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:If the proxy is adding path data, discard part of the path to fix redirects and links by using StartsWithSegments 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();
});

Konfiguration für einen Proxy, der andere Headernamen verwendetConfiguration for a proxy that uses different header names

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:If the proxy doesn't use headers named X-Forwarded-For and X-Forwarded-Proto to forward the proxy address/port and originating scheme information, set the ForwardedForHeaderName and ForwardedProtoHeaderName options to match the header names used by the proxy:

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

Konfiguration für eine IPv4-Adresse, die als IPv6-Adresse dargestellt wirdConfiguration for an IPv4 address represented as an IPv6 address

Wenn der Server Dualmodussockets verwendet, werden IPv4-Adressen in einem IPv6-Format bereitgestellt (z.B. wird 10.0.0.1 in IPv4 in IPv6 als ::ffff:10.0.0.1 oder ::ffff:a00:1 dargestellt).If the server is using dual-mode sockets, IPv4 addresses are supplied in an IPv6 format (for example, 10.0.0.1 in IPv4 represented in IPv6 as ::ffff:10.0.0.1 or ::ffff:a00:1). Siehe IPAddress.MapToIPv6.See IPAddress.MapToIPv6. Bestimmen Sie mithilfe der HttpContext.Connection.RemoteIpAddress, ob dieses Format erforderlich ist.Determine if this format is required by looking at the HttpContext.Connection.RemoteIpAddress.

Im folgenden Beispiel wird eine Netzwerkadresse, die weitergeleitete Header bereitstellt, der KnownNetworks-Liste im IPv6-Format hinzugefügt.In the following example, a network address that supplies forwarded headers is added to the KnownNetworks list in IPv6 format.

IPv4-Adresse: 10.11.12.1/8IPv4 address: 10.11.12.1/8

Konvertierte IPv6-Adresse: ::ffff:10.11.12.1Converted IPv6 address: ::ffff:10.11.12.1
Konvertierte Präfixlänge: 104Converted prefix length: 104

Sie können die Adresse auch im Hexadezimalformat angeben (10.11.12.1 in IPv6 als ::ffff:0a0b:0c01 dargestellt).You can also supply the address in hexadecimal format (10.11.12.1 represented in IPv6 as ::ffff:0a0b:0c01). Fügen Sie bei der Konvertierung einer IPv4-Adresse in IPv6 der CIDR-Präfixlänge 96 (8 im Beispiel) für das zusätzliche ::ffff:-IPv6-Präfix hinzu (8 + 96 = 104).When converting an IPv4 address to IPv6, add 96 to the CIDR Prefix Length (8 in the example) to account for the additional ::ffff: IPv6 prefix (8 + 96 = 104).

// To access IPNetwork and IPAddress, add the following namespaces:
// using using System.Net;
// using Microsoft.AspNetCore.HttpOverrides;
services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders =
        ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto;
    options.KnownNetworks.Add(new IPNetwork(
        IPAddress.Parse("::ffff:10.11.12.1"), 104));
});

Das Schema für Linux- und Nicht-IIS-Reverseproxys weiterleitenForward the scheme for Linux and non-IIS reverse proxies

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.Apps that call UseHttpsRedirection and UseHsts put a site into an infinite loop if deployed to an Azure Linux App Service, Azure Linux virtual machine (VM), or behind any other reverse proxy besides IIS. TLS wird vom Reverseproxy beendet, und Kestrel wird nicht auf das richtige Anforderungsschema aufmerksam gemacht.TLS is terminated by the reverse proxy, and Kestrel isn't made aware of the correct request scheme. OAuth und OIDC schlagen in dieser Konfiguration ebenfalls fehl, weil sie falsche Umleitungen generieren.OAuth and OIDC also fail in this configuration because they generate incorrect redirects. 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).UseIISIntegration adds and configures Forwarded Headers Middleware when running behind IIS, but there's no matching automatic configuration for Linux (Apache or 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.To forward the scheme from the proxy in non-IIS scenarios, add and configure Forwarded Headers Middleware. In Startup.ConfigureServices verwenden Sie folgenden Code:In Startup.ConfigureServices, use the following 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();
    });
}

ProblembehandlungTroubleshoot

Wenn Header nicht wie erwartet zugewiesen werden, aktivieren Sie die Protokollierung.When headers aren't forwarded as expected, enable logging. Wenn die Protokolle nicht genügend Informationen zur Problembehandlung bereitstellen, listen Sie die vom Server empfangenen Anforderungsheader auf.If the logs don't provide sufficient information to troubleshoot the problem, enumerate the request headers received by the server. Verwenden Sie Inlinemiddleware, um Anforderungsheader in eine App-Antwort zu schreiben oder die Header zu protokollieren.Use inline middleware to write request headers to an app response or log the headers.

Um die Header in die Antwort der App zu schreiben, platzieren Sie die folgende Terminalinlinemiddleware unmittelbar hinter den Aufruf von UseForwardedHeaders in Startup.Configure:To write the headers to the app's response, place the following terminal inline middleware immediately after the call to 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.You can write to logs instead of the response body. Das Schreiben in Protokolle ermöglicht es der Website, während des Debuggens normal zu funktionieren.Writing to logs allows the site to function normally while debugging.

So schreiben Sie in Protokolle und nicht in den Antworttext:To write logs rather than to the response body:

app.Use(async (context, next) =>
{
    // Request method, scheme, and 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);

    // 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}-Werte in X-Original-{For|Proto|Host} verschoben.When processed, X-Forwarded-{For|Proto|Host} values are moved to X-Original-{For|Proto|Host}. Wenn in einem bestimmten Header mehrere Werte vorhanden sind, verarbeitet die Middleware der Weiterleitungsheader die Header in umgekehrter Reihenfolge von rechts nach links.If there are multiple values in a given header, Forwarded Headers Middleware processes headers in reverse order from right to left. 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.The default ForwardLimit is 1 (one), so only the rightmost value from the headers is processed unless the value of ForwardLimit is increased.

Die ursprüngliche IP-Remoteadresse der Anforderung muss mit einem Eintrag in den KnownProxies- oder KnownNetworks-Listen übereinstimmen, bevor weitergeleitete Header verarbeitet werden.The request's original remote IP must match an entry in the KnownProxies or KnownNetworks lists before forwarded headers are processed. Auf diese Weise wird das Headerspoofing begrenzt, da keine Weiterleitungen von nicht vertrauenswürdigen Proxys akzeptiert werden.This limits header spoofing by not accepting forwarders from untrusted proxies. Wenn ein unbekannter Proxy erkannt wird, gibt die Protokollierung die Adresse des Proxys an:When an unknown proxy is detected, logging indicates the address of the proxy:

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

Im vorherigen Beispiel ist 10.0.0.100 ein Proxyserver.In the preceding example, 10.0.0.100 is a proxy server. 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.If the server is a trusted proxy, add the server's IP address to KnownProxies (or add a trusted network to KnownNetworks) in Startup.ConfigureServices. Weitere Informationen finden Sie im Abschnitt Middleware für weitergeleitete Header: Optionen.For more information, see the Forwarded Headers Middleware options section.

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

Wichtig

Erlauben Sie nur vertrauenswürdigen Proxys und Netzwerken die Weiterleitung von Headern.Only allow trusted proxies and networks to forward headers. Andernfalls sind Angriffe des Typs IP-Spoofing möglich.Otherwise, IP spoofing attacks are possible.

Zusätzliche RessourcenAdditional resources