Konfigurieren von Endpunkten für den ASP.NET Core-Kestrel-Webserver

Artikel
11/06/2024

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Warnung

Diese Version von ASP.NET Core wird nicht mehr unterstützt. Weitere Informationen finden Sie in der .NET- und .NET Core-Supportrichtlinie. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Warnung

Wichtig

Die aktuelle Version finden Sie in der .NET 9-Version dieses Artikels.

Kestrel-Endpunkte stellen die Infrastruktur zum Lauschen auf eingehende Anforderungen und zum Weiterleiten an die entsprechende Middleware bereit. Die Kombination aus einer Adresse und einem Protokoll definiert einen Endpunkt.

Die Adresse gibt die Netzwerkschnittstelle an, an der der Server auf eingehende Anforderungen lauscht, etwa einen TCP-Port.
Das Protokoll gibt die Kommunikation zwischen Client und Server an, z. B. HTTP/1.1, HTTP/2 oder HTTP/3.
Ein Endpunkt kann mithilfe des https-URL-Schemas oder der UseHttps-Methode gesichert werden.

Endpunkte können mithilfe von URLs, JSON in appsettings.json und Code konfiguriert werden. In diesem Artikel wird erläutert, wie Sie die einzelnen Optionen zum Konfigurieren eines Endpunkts verwenden:

Konfigurieren von Endpunkten
Konfigurieren von HTTPS
Konfigurieren von HTTP-Protokollen

Standardendpunkt

Neue ASP.NET Core-Projekte sind so konfiguriert, dass sie an einen beliebigen HTTP-Port im Bereich 5000 bis 5300 und einen beliebigen HTTPS-Port im Bereich 7000 bis 7300 gebunden werden. Die ausgewählten Ports werden in der generierten Datei Properties/launchSettings.json gespeichert und können vom Entwickler geändert werden. Die Datei launchSetting.json wird nur für die lokale Entwicklung verwendet.

Wenn keine Endpunktkonfiguration vorhanden ist, wird Kestrel an http://localhost:5000 gebunden.

Konfigurieren von Endpunkten

Kestrel-Endpunkte lauschen auf eingehende Verbindungen. Wenn ein Endpunkt erstellt wird, muss er mit der Adresse konfiguriert werden, auf die er lauscht. In der Regel handelt es sich hierbei um eine TCP-Adresse und eine Portnummer.

Es gibt mehrere Optionen zum Konfigurieren von Endpunkten:

Konfigurieren von Endpunkten mit URLs
Reine Angabe von Ports
Konfigurieren von Endpunkten in „appsettings.json“
Konfigurieren von Endpunkten im Code

Konfigurieren von Endpunkten mit URLs

In den folgenden Abschnitten wird erläutert, wie Endpunkte mithilfe folgender Elemente konfiguriert werden:

Die Umgebungsvariable ASPNETCORE_URLS
Das Befehlszeilenargument --urls
Den Hostkonfigurationsschlüssel urls
Die Erweiterungsmethode UseUrls
WebApplication.Urls-Eigenschaft.

URL-Formate

Die URLs geben die IP- oder Hostadressen mit Ports und Protokollen an, denen der Server lauschen soll. Der Port kann weggelassen werden, wenn er der Standard für das Protokoll ist (in der Regel 80 und 443). URLs können eins der folgenden Formate aufweisen:

IPv4-Adresse mit Portnummer
```
http://65.55.39.10:80/
```
Bei 0.0.0.0 handelt es sich um einen Sonderfall, für den eine Bindung an alle IPv4-Adressen erfolgt.
IPv6-Adresse mit Portnummer
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] stellt das Äquivalent von IPv6 zu 0.0.0.0 für IPv4 dar.
Platzhalterhost mit Portnummer
```
http://contoso.com:80/
http://*:80/
```
Alle Elemente, die nicht als gültige IP-Adresse oder localhost erkannt werden, werden als Platzhalter behandelt, der an alle IPv4- und IPv6-IP-Adressen gebunden wird. Einige Benutzer*innen bevorzugen zur expliziteren Angabe die Verwendung von * oder +. Verwenden Sie HTTP.sys oder einen Reverseproxyserver zum Binden verschiedener Hostnamen an verschiedene ASP.NET Core-Apps auf demselben Port.

Beispiele für Reverseproxyserver sind IIS, YARP, Nginx und Apache.
Hostname localhost mit Portnummer oder Loopback-IP mit Portnummer
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Wenn localhost angegeben ist, versucht Kestrel, eine Bindung zu IPv4- und IPv6-Loopback-Schnittstellen zu erstellen. Wenn der erforderliche Port von einem anderen Dienst auf einer der Loopback-Schnittstellen verwendet wird, tritt beim Starten von Kestrel ein Fehler auf. Wenn eine der Loopback-Schnittstellen aus anderen Gründen nicht verfügbar ist (meistens durch die fehlende Unterstützung von IPv6), protokolliert Kestrel eine Warnung.

Mithilfe eines Semikolons (;) als Trennzeichens können mehrere URL-Präfixe angegeben werden:

http://*:5000;http://localhost:5001;https://hostname:5002

Weitere Informationen finden Sie unter Außerkraftsetzen der Konfiguration.

HTTPS-URL-Präfixe

HTTPS-URL-Präfixe können nur zum Definieren von Endpunkten verwendet werden, wenn ein Standardzertifikat in der HTTPS-Endpunktkonfiguration bereitgestellt wird. Verwenden Sie beispielsweise die KestrelServerOptions-Konfiguration oder eine Konfigurationsdatei, wie weiter unten in diesem Artikel gezeigt.

Weitere Informationen finden Sie unter Konfigurieren von HTTPS.

Reine Angabe von Ports

Apps und Container erhalten häufig nur einen Port, dem sie lauschen können, z. B. Port 80, und keine zusätzlichen Einschränkungen für den Host oder Pfad. HTTP_PORTS und HTTPS_PORTS sind Konfigurationsschlüssel, die die Lauschports für Kestrel- und HTTP.sys-Server angeben. Diese Schlüssel können als Umgebungsvariablen, die mit den Präfixen DOTNET_ oder ASPNETCORE_ definiert sind, oder direkt über andere Konfigurationseingaben wie appsettings.json angegeben werden. Jede ist eine durch Semikolons getrennte Liste mit Portwerten. Dies wird im folgenden Beispiel veranschaulicht:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Das obige Beispiel ist eine Kurzform der folgenden Konfiguration, die das Schema (HTTP oder HTTPS) und alle Hosts oder IP-Adressen angibt.

ASPNETCORE_URLS=http://*:80/;http://*:8080/;https://*:443/;https://*:8081/

Die Konfigurationsschlüssel HTTP_PORTS und HTTPS_PORTS haben eine niedrigere Priorität und werden von URLs oder Werten überschrieben, die direkt im Code angegeben werden. Zertifikate müssen weiterhin separat über serverspezifische Mechanismen für HTTPS konfiguriert werden.

Konfigurieren von Endpunkten in „appsettings.json“

Kestrel kann Endpunkte aus einer IConfiguration-Instanz laden. Die Kestrel-Konfiguration wird standardmäßig aus dem Abschnitt Kestrel geladen, und Endpunkte werden in Kestrel:Endpoints konfiguriert:

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpEndpoint": {
        "Url": "http://localhost:8080"
      }
    }
  }
}

Für das vorherige Beispiel gilt Folgendes:

Verwendet appsettings.json als Konfigurationsquelle. Es kann jedoch eine beliebige IConfiguration-Quelle verwendet werden.
Fügt einen Endpunkt mit dem Namen MyHttpEndpoint an Port 8080 hinzu.

Weitere Informationen zum Konfigurieren von Endpunkten mit JSON finden Sie in späteren Abschnitten in diesem Artikel, in denen das Konfigurieren von HTTPS und das Konfigurieren von HTTP-Protokollen in „appsettings.json“ erläutert werden.

Erneutes Laden von Endpunkten aus der Konfiguration

Das erneute Laden der Endpunktkonfiguration, wenn sich die Konfigurationsquelle ändert, ist standardmäßig aktiviert. Sie kann mithilfe von KestrelServerOptions.Configure(IConfiguration, Boolean) deaktiviert werden.

Wenn eine Änderung signalisiert wird, werden die folgenden Schritte ausgeführt:

Die neue Konfiguration wird mit der alten verglichen, und Endpunkte ohne Konfigurationsänderungen werden nicht geändert.
Entfernte oder geänderte Endpunkte erhalten 5 Sekunden, um die Verarbeitung von Anforderungen abzuschließen und herunterzufahren.
Neue oder geänderte Endpunkte werden gestartet.

Clients, die eine Verbindung mit einem geänderten Endpunkt herstellen, werden möglicherweise getrennt oder abgelehnt, wenn der Endpunkt neu gestartet wird.

ConfigurationLoader

KestrelServerOptions.Configure gibt einen Wert vom Typ KestrelConfigurationLoader zurück. Die Methode Endpoint(String, Action<EndpointConfiguration>) des Ladeprogramms, mit der die Einstellungen eines Endpunkts ergänzt werden können:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    var kestrelSection = context.Configuration.GetSection("Kestrel");

    serverOptions.Configure(kestrelSection)
        .Endpoint("HTTPS", listenOptions =>
        {
            // ...
        });
});

Auf KestrelServerOptions.ConfigurationLoader kann direkt zugegriffen werden, um die Iteration auf dem vorhandenen Ladeprogramm fortzusetzen, etwa auf dem von WebApplicationBuilder.WebHost bereitgestellten Ladeprogramm.

Der Konfigurationsabschnitt ist für jeden Endpunkt in den Optionen der Methode Endpoint verfügbar, sodass benutzerdefinierte Einstellungen gelesen werden können.
KestrelServerOptions.Configure(IConfiguration) kann mehrfach aufgerufen werden, aber nur die letzte Konfiguration wird verwendet, es sei denn, Load wird explizit für frühere Instanzen aufgerufen. Der Standardhost ruft Load nicht auf, sodass der Abschnitt mit der Standardkonfiguration ersetzt werden kann.
KestrelConfigurationLoader spiegelt die API-Familie Listen von KestrelServerOptions als Endpoint-Überladungen, weshalb Code und Konfigurationsendpunkte am selben Ort konfiguriert werden können. Diese Überladungen verwenden keine Namen und nutzen nur Standardeinstellungen aus der Konfiguration.

Konfigurieren von Endpunkten im Code

KestrelServerOptions stellt Methoden zum Konfigurieren von Endpunkten im Code bereit:

Wenn die APIs Listen und UseUrls gleichzeitig verwendet werden, überschreiben die Listen-Endpunkte die UseUrls-Endpunkte.

Binden an einen TCP-Socket

Die Methoden Listen, ListenLocalhost und ListenAnyIP werden an einen TCP-Socket gebunden:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Für das vorherige Beispiel gilt Folgendes:

Konfiguriert Endpunkte, die an Port 5000 und 5001 lauschen.
Konfiguriert HTTPS für einen Endpunkt mit der Erweiterungsmethode UseHttps für ListenOptions. Weitere Informationen finden Sie unter Konfigurieren von HTTPS im Code.

Unter Windows können selbstsignierte Zertifikate mit dem PowerShell-Cmdlet New-SelfSignedCertificate erstellt werden. Ein nicht unterstütztes Beispiel finden Sie unter UpdateIISExpressSSLForChrome.ps1.

Unter macOS, Linux und Windows können Zertifikate mithilfe von OpenSSL erstellt werden.

Binden an einen Unix-Socket

Wie in diesem Beispiel dargestellt, lauschen Sie an einem Unix-Socket mit ListenUnixSocket, um eine verbesserte Leistung mit Nginx zu erzielen:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
});

Legen Sie den Eintrag server>location>proxy_pass in der Nginx-Konfigurationsdatei auf http://unix:/tmp/{KESTREL SOCKET}:/; fest. {KESTREL SOCKET} ist der Name des für ListenUnixSocket bereitgestellten Socket (zum Beispiel kestrel-test.sock im vorherigen Beispiel).
Stellen Sie sicher, dass der Socket von Nginx beschreibbar ist (z. B. chmod go+w /tmp/kestrel-test.sock).

Konfigurieren von Endpunktstandardeinstellungen

ConfigureEndpointDefaults(Action<ListenOptions>) gibt die Konfiguration an, die für jeden angegebenen Endpunkt ausgeführt wird. Das mehrfache Aufrufen von ConfigureEndpointDefaults ersetzt die vorherige Konfiguration.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });
});

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureEndpointDefaults erstellt werden, werden die Standardwerte nicht angewendet.

Dynamische Portbindung

Wenn die Portnummer 0 angegeben wird, wird Kestrel dynamisch an einen verfügbaren Port gebunden. Im folgenden Beispiel wird veranschaulicht, wie bestimmt werden kann, für welchen Port Kestrel zur Laufzeit eine Bindung erstellt hat:

app.Run(async (context) =>
{
    var serverAddressFeature = context.Features.Get<IServerAddressesFeature>();

    if (serverAddressFeature is not null)
    {
        var listenAddresses = string.Join(", ", serverAddressFeature.Addresses);

        // ...
    }
});

Das dynamische Binden eines Ports ist in einigen Situationen nicht verfügbar:

KestrelServerOptions.ListenLocalhost
Binden von TCP-basiertem HTTP/1.1 oder HTTP/2 mit QUIC-basiertem HTTP/3.

Konfigurieren von HTTPS

Kestrel unterstützt das Schützen von Endpunkten mit HTTPS. Über HTTPS gesendete Daten werden mithilfe von Transport Layer Security (TLS) verschlüsselt, um die Sicherheit der zwischen Client und Server übertragenen Daten zu erhöhen.

HTTPS erfordert ein TLS-Zertifikat. Das TLS-Zertifikat wird auf dem Server gespeichert, und Kestrel wird für seine Verwendung konfiguriert. Eine App kann das ASP.NET Core-HTTPS-Entwicklungszertifikat in einer lokalen Entwicklungsumgebung verwenden. Das Entwicklungszertifikat wird in Umgebungen, die nicht für die Entwicklung vorgesehen sind, nicht installiert. In der Produktion muss ein TLS-Zertifikat explizit konfiguriert sein. Zumindest muss ein Standardzertifikat angegeben werden.

Die Art und Weise, wie HTTPS und das TLS-Zertifikat konfiguriert werden, hängt davon ab, wie Endpunkte konfiguriert werden:

Wenn URL-Präfixe oder nur Ports zum Definieren von Endpunkten verwendet werden, kann HTTPS nur verwendet werden, wenn in der HTTPS-Endpunktkonfiguration ein Standardzertifikat bereitgestellt wird. Ein Standardzertifikat kann mit einer der folgenden Optionen konfiguriert werden:
Konfigurieren von HTTPS in „appsettings.json“
Konfigurieren von HTTPS im Code

Konfigurieren von HTTPS in „appsettings.json“

Ein Standardkonfigurationsschema für HTTPS-App-Einstellungen ist für Kestrel verfügbar. Konfigurieren Sie mehrere Endpunkte, einschließlich der zu verwendenden URLs und Zertifikate aus einer Datei auf dem Datenträger oder einem Zertifikatspeicher.

Jeder HTTPS-Endpunkt, der kein Zertifikat angibt (im folgenden Beispiel HttpsDefaultCert), greift auf das unter Certificates:Default festgelegte Zertifikat oder das Entwicklungszertifikat zurück.

Das folgende Beispiel gilt für appsettings.json, es kann aber eine beliebige Konfigurationsquelle verwendet werden:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Warnung

Im vorherigen Beispiel wird das Zertifikatkennwort als Klartext in appsettings.json gespeichert. Das Token $CREDENTIAL_PLACEHOLDER$ dient als Platzhalter für das Kennwort des Zertifikats. Informationen zum sicheren Speichern von Zertifikatkennwörtern in Entwicklungsumgebungen finden Sie unter Schützen von Geheimnissen in der Entwicklung. Informationen zum sicheren Speichern von Zertifikatkennwörtern in Produktionsumgebungen finden Sie unter Azure Key Vault-Konfigurationsanbieter. Entwicklungsgeheimnisse sollten nicht in Produktions- oder Testumgebungen verwendet werden.

Schemahinweise

Bei den Namen der Endpunkte wird die Groß-/Kleinschreibung nicht beachtet. HTTPS and Https gleichwertig.
Der Parameter Url ist für jeden Endpunkt erforderlich. Das Format für diesen Parameter ist identisch mit dem allgemeinen Konfigurationsparameter Urls, mit der Ausnahme, dass er auf einen einzelnen Wert begrenzt ist. Siehe URL-Formate weiter oben in diesem Artikel.
Diese Endpunkte ersetzen die in der allgemeinen Urls-Konfiguration festgelegten Endpunkte, anstatt sie zu ergänzen. Endpunkte, die über Listen in Code definiert werden, werden den im Konfigurationsabschnitt definierten Endpunkten hinzugefügt.
Der Certificate-Abschnitt ist optional. Wenn der Certificate-Abschnitt nicht angegeben ist, werden die in Certificates:Default definierten Standardwerte verwendet. Wenn keine Standardwerte verfügbar sind, wird das Entwicklungszertifikat verwendet. Wenn weder Standardwerte noch Entwicklungszertifikat vorhanden sind, löst der Server eine Ausnahme aus und kann nicht gestartet werden.
Der Certificate-Abschnitt unterstützt mehrere Zertifikatquellen.
In Configuration kann eine beliebige Anzahl von Endpunkten definiert werden, solange sie keine Portkonflikte verursachen.

Zertifikatquellen

Zertifikatknoten können so konfiguriert werden, dass Zertifikate aus einer Reihe von Quellen geladen werden:

Path und Password zum Laden von .pfx-Dateien.
Path, KeyPath und Password zum Laden von .pem/.crt- und .key-Dateien.
Subject und Store zum Laden aus dem Zertifikatspeicher.

Das Zertifikat unter Certificates:Default kann beispielweise wie folgt angegeben werden:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

Konfigurieren von Clientzertifikaten in „appsettings.json“

ClientCertificateMode wird zum Konfigurieren des Clientzertifikatverhaltens verwendet.

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Warnung

Der Standardwert ist ClientCertificateMode.NoCertificate, wobei Kestrel kein Zertifikat vom Client anfordert oder verlangt.

Weitere Informationen finden Sie unter Konfigurieren der Zertifikatauthentifizierung in ASP.NET Core.

Konfigurieren von SSL-/TLS-Protokollen in „appsettings.json“

SSL-Protokolle werden zum Verschlüsseln und Entschlüsseln von Datenverkehr zwischen zwei Peers verwendet werden, üblicherweise ein Client und ein Server.

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Warnung

Der Standardwert SslProtocols.None bewirkt, dass Kestrel das Betriebssystem standardmäßig verwendet, um das beste Protokoll auszuwählen. Verwenden Sie den Standardwert, es sei denn, Sie haben einen bestimmten Grund für die Auswahl eines Protokolls.

Konfigurieren von HTTPS im Code

Wenn Sie die API Listen verwenden, steht die Erweiterungsmethode UseHttps für ListenOptions zum Konfigurieren von HTTPS zur Verfügung.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

ListenOptions.UseHttps-Parameter:

filename entspricht dem Pfad und Dateinamen einer Zertifikatdatei relativ zu dem Verzeichnis, das die Inhaltsdateien der App enthält.
password ist das für den Zugriff auf die X.509-Zertifikatsdaten erforderliche Kennwort.
configureOptions ist eine Action zum Konfigurieren von HttpsConnectionAdapterOptions. Gibt ListenOptions zurück.
storeName ist der Zertifikatspeicher, aus dem das Zertifikat geladen wird.
subject ist der Name des Antragstellers für das Zertifikat.
allowInvalid gibt an, ob ungültige Zertifikate berücksichtigt werden sollten, z.B. selbstsignierte Zertifikate.
location ist der Speicherort, aus dem das Zertifikat geladen wird.
serverCertificate ist das X.509-Zertifikat.

Eine vollständige Liste der UseHttps-Überladungen finden Sie unter UseHttps.

Konfigurieren von Clientzertifikaten im Code

ClientCertificateMode konfiguriert die Clientzertifikatanforderungen.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

Der Standardwert ist NoCertificate, wobei Kestrel kein Zertifikat vom Client anfordert oder verlangt.

Weitere Informationen finden Sie unter Konfigurieren der Zertifikatauthentifizierung in ASP.NET Core.

Konfigurieren von HTTPS-Standardwerten im Code

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) gibt eine Konfigurationsaktion (Action) an, die für jeden HTTPS-Endpunkt ausgeführt werden soll. Mehrmalige Aufrufe von ConfigureHttpsDefaults ersetzen vorherige Instanzen von Action mit der zuletzt angegebenen Action-Instanz.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureHttpsDefaults erstellt werden, werden die Standardwerte nicht angewendet.

Konfigurieren von SSL-/TLS-Protokollen im Code

SSL-Protokolle werden zum Verschlüsseln und Entschlüsseln von Datenverkehr zwischen zwei Peers verwendet werden, üblicherweise ein Client und ein Server.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

Konfigurieren des Filters für TLS-Suites mit Verschlüsselungsverfahren im Code

Unter Linux kann CipherSuitesPolicy zum Filtern von TLS-Handshakes auf Verbindungsbasis verwendet werden:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Konfigurieren der Servernamensanzeige

Die Servernamensanzeige (SNI) kann zum Hosten mehrerer Domänen auf der gleichen IP-Adresse und dem gleichen Port verwendet werden. SNI kann verwendet werden, um Ressourcen zu schonen, indem mehrere Websites von einem Server aus bedient werden.

Damit die Servernamensanzeige funktioniert, sendet der Client während des TLS-Handshakes den Hostnamen für die sichere Sitzung an den Server, sodass der Server das richtige Zertifikat bereitstellen kann. Der Client verwendet das beigestellte Zertifikat für die verschlüsselte Kommunikation mit dem Server während der sicheren Sitzung nach dem TLS-Handshake.

Alle Websites müssen in derselben Kestrel-Instanz ausgeführt werden. Kestrel unterstützt ohne Reverseproxy keine gemeinsame IP-Adresse und keinen gemeinsamen Port für mehrere Instanzen.

SNI kann in zwei Varianten konfiguriert werden:

Konfigurieren Sie in der Konfiguration eine Zuordnung zwischen Hostnamen und HTTPS-Optionen. Beispiel: JSON in der appsettings.json-Datei.
Erstellen Sie einen Endpunkt im Code, und wählen Sie ein Zertifikat mit dem Hostnamen und dem ServerCertificateSelector-Rückruf aus.

Konfigurieren von SNI in „appsettings.json“

Kestrel unterstützt SNI, die in der Konfiguration definiert ist. Ein Endpunkt kann mit einem Sni-Objekt konfiguriert werden, das eine Zuordnung zwischen Hostnamen und HTTPS-Optionen enthält. Der Name des Verbindungshosts wird mit den Optionen abgeglichen, und sie werden für diese Verbindung verwendet.

Die folgende Konfiguration fügt einen Endpunkt namens MySniEndpoint hinzu, der SNI verwendet, um HTTPS-Optionen basierend auf dem Hostnamen auszuwählen:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Warnung

HTTPS-Optionen, die von SNI überschrieben werden können:

Certificate konfiguriert die Zertifikatquelle.
Protocols konfiguriert die zulässigen HTTP-Protokolle.
SslProtocols konfiguriert die zulässigen SSL-Protokolle.
ClientCertificateMode konfiguriert die Clientzertifikatanforderungen.

Der Hostname unterstützt Platzhalterabgleiche:

Genaue Übereinstimmung. Beispielsweise entspricht a.example.orga.example.org.
Platzhalterpräfix. Wenn es mehrere Platzhalterübereinstimmungen gibt, wird das längste Muster ausgewählt. Beispielsweise entspricht *.example.orgb.example.org und c.example.org.
Vollständiger Platzhalter. * entspricht allem anderen, einschließlich Clients, die SNI nicht verwenden und keinen Hostnamen senden.

Die abgeglichene SNI-Konfiguration wird auf den Endpunkt für die Verbindung angewendet, wobei Werte für den Endpunkt überschrieben werden. Wenn eine Verbindung nicht mit einem konfigurierten SNI-Hostnamen übereinstimmt ist, wird die Verbindung verweigert.

Konfigurieren von SNI mit Code

Kestrel unterstützt SNI mit mehreren Rückruf-APIs:

ServerCertificateSelector
ServerOptionsSelectionCallback
TlsHandshakeCallbackOptions

SNI mit `ServerCertificateSelector`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase)
            {
                ["localhost"] = localhostCert,
                ["example.com"] = exampleCert,
                ["sub.example.com"] = subExampleCert
            };

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name is not null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI mit `ServerOptionsSelectionCallback`

Kestrel unterstützt zusätzliche dynamische TLS-Konfiguration über den ServerOptionsSelectionCallback-Rückruf. Der Rückruf wird für jede Verbindung einmal aufgerufen, um der App zu ermöglichen, den Hostnamen zu überprüfen und das entsprechende Zertifikat sowie die TLS-Konfiguration auszuwählen. Standardzertifikate und ConfigureHttpsDefaults werden mit diesem Callback nicht verwendet.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost",
                    StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = localhostCert,
                            // Different TLS requirements for this host
                            ClientCertificateRequired = true
                        });
                }

                return new ValueTask<SslServerAuthenticationOptions>(
                    new SslServerAuthenticationOptions
                    {
                        ServerCertificate = exampleCert
                    });
            }, state: null!);
        });
    });
});

SNI mit `TlsHandshakeCallbackOptions`

Kestrel unterstützt zusätzliche dynamische TLS-Konfiguration über den TlsHandshakeCallbackOptions.OnConnection-Rückruf. Der Rückruf wird für jede Verbindung einmal aufgerufen, um der App zu ermöglichen, den Hostnamen zu überprüfen, das entsprechende Zertifikat, die TLS-Konfiguration und andere Serveroptionen auszuwählen. Standardzertifikate und ConfigureHttpsDefaults werden mit diesem Callback nicht verwendet.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps(new TlsHandshakeCallbackOptions
            {
                OnConnection = context =>
                {
                    if (string.Equals(context.ClientHelloInfo.ServerName, "localhost",
                        StringComparison.OrdinalIgnoreCase))
                    {
                        // Different TLS requirements for this host
                        context.AllowDelayedClientCertificateNegotation = true;

                        return new ValueTask<SslServerAuthenticationOptions>(
                            new SslServerAuthenticationOptions
                            {
                                ServerCertificate = localhostCert
                            });
                    }

                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = exampleCert
                        });
                }
            });
        });
    });
});

Konfigurieren von HTTP-Protokollen

Kestrel unterstützt alle häufig verwendeten HTTP-Versionen. Endpunkte können mithilfe der HttpProtocols-Enumeration so konfiguriert werden, dass sie unterschiedliche HTTP-Versionen unterstützen. Diese Enumeration gibt die verfügbaren HTTP-Versionsoptionen an.

TLS ist erforderlich, um mehrere HTTP-Versionen zu unterstützen. Der TLS Application-Layer Protocol Negotiation (ALPN)-Handshake wird zur Aushandlung des Verbindungsprotokolls zwischen dem Client und dem Server verwendet, wenn ein Endpunkt mehrere Protokolle unterstützt.

`HttpProtocols`-Wert	Zulässiges Verbindungsprotokoll
`Http1`	Nur HTTP/1.1. Kann mit oder ohne TLS verwendet werden.
`Http2`	Nur HTTP/2. Kann nur ohne TLS verwendet werden, wenn der Client einen Vorabkenntnis-Modus unterstützt.
`Http3`	Nur HTTP/3 Erfordert TLS Der Client muss möglicherweise für die ausschließliche Verwendung von HTTP/3 konfiguriert werden.
`Http1AndHttp2`	HTTP/1.1 und HTTP/2. Für HTTP/2 muss der Client HTTP/2 im TLS ALPN-Handshake (Application-Layer Protocol Negotiation) auswählen, andernfalls wird standardmäßig eine HTTP/1.1 verwendet.
`Http1AndHttp2AndHttp3`	HTTP/1.1, HTTP/2 und HTTP/3. Die erste Clientanforderung verwendet normalerweise HTTP/1.1 oder HTTP/2, und der `alt-svc`-Antwortheader fordert den Client auf, ein Upgrade auf HTTP/3 durchzuführen. HTTP/2 und HTTP/3 erfordern TLS. Andernfalls wird für die Verbindung standardmäßig HTTP/1.1 verwendet.

Der Standardprotokollwert für einen Endpunkt ist HttpProtocols.Http1AndHttp2.

TLS-Einschränkungen für HTTP/2:

TLS Version 1.2 oder höher
Erneute Aushandlung deaktiviert
Komprimierung deaktiviert
Minimale Größen für Austausch von flüchtigen Schlüsseln:
- ECDHE (Elliptic Curve Diffie-Hellman) [RFC4492]: mindestens 224 Bit
- DHE (Finite Field Diffie-Hellman) [TLS12]: mindestens 2048 Bit
Verschlüsselungssammlung nicht verboten

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] mit der elliptischen P-256-Kurve [FIPS186] wird standardmäßig unterstützt.

Konfigurieren von HTTP-Protokollen in „appsettings.json“

Das folgende appsettings.json -Beispiel richtet HTTP/1.1 als Verbindungsprotokoll für einen bestimmten Endpunkt ein:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Im Abschnitt Kestrel:EndpointDefaults kann ein Standardprotokoll konfiguriert werden. Das folgende appsettings.json -Beispiel richtet HTTP/1.1 als Standardverbindungsprotokoll für alle Endpunkte ein:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Protokolle, die in Code angegeben werden, setzen Werte außer Kraft, der durch die Konfiguration festgelegt werden.

Konfigurieren von HTTP-Protokollen im Code

ListenOptions.Protocols wird verwendet, um Protokolle mit der HttpProtocols-Enumeration anzugeben.

Das folgende Beispiel konfiguriert einen Endpunkt für HTTP/1.1-, HTTP/2- und HTTP/3-Verbindungen an Port 8000. Die Verbindungen werden durch TLS mit einem bereitgestellten Zertifikat geschützt:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
    });
});

Weitere Informationen

ASP.NET Core-Projekte sind so konfiguriert, dass sie an einen beliebigen HTTP-Port im Bereich 5000-5300 und einen beliebigen HTTPS-Port im Bereich 7000-7300 gebunden werden. Diese Standardkonfiguration wird in der generierten Datei Properties/launchSettings.json angegeben und kann überschrieben werden. Wenn keine Ports angegeben sind, erfolgt die Bindung von Kestrel an http://localhost:5000.

Verwenden Sie Folgendes zum Angeben der URLs:

Die Umgebungsvariable ASPNETCORE_URLS
Das Befehlszeilenargument --urls
Den Hostkonfigurationsschlüssel urls
Die Erweiterungsmethode UseUrls

Der Wert, der mit diesen Ansätzen angegeben wird, kann mindestens ein HTTP- oder HTTPS-Endpunkt sein (HTTPS wenn ein Standardzertifikat verfügbar ist). Konfigurieren Sie den Wert als eine durch Semikolons getrennte Liste (z.B. "Urls": "http://localhost:8000;http://localhost:8001").

Weitere Informationen zu diesen Ansätzen finden Sie unter Server-URLs und Außerkraftsetzen der Konfiguration.

Ein Entwicklungszertifikat wird erstellt:

Bei Installation des .NET SDK
Das dev-cert-Tool wird zum Erstellen eines Zertifikats verwendet.

Das Entwicklungszertifikat ist nur für den Benutzer verfügbar, der das Zertifikat generiert. Einige Browser erfordern, dass Sie die explizite Berechtigung erteilen, dem lokalen Entwicklungszertifikat zu vertrauen.

Projektvorlagen konfigurieren Apps, damit sie standardmäßig auf HTTPS ausgeführt werden und die HTTPS-Umleitung und HSTS-Unterstützung enthalten.

Rufen Sie die Listen- oder ListenUnixSocket-Methode unter KestrelServerOptions auf, um URL-Präfixe und Ports für Kestrel zu konfigurieren.

UseUrls, das Befehlszeilenargument --urls, der Hostkonfigurationsschlüssel urls und die Umgebungsvariable ASPNETCORE_URLS funktionieren ebenfalls, verfügen jedoch über Einschränkungen, die im Verlauf dieses Abschnitts erläutert werden (Ein Standardzertifikat muss für die HTTPS-Endpunktkonfiguration verfügbar sein).

KestrelServerOptions-Konfiguration:

ConfigureEndpointDefaults

ConfigureEndpointDefaults(Action<ListenOptions>)Gibt die Konfiguration Action zum Ausführen von jedem angegebenen Endpunkt an. Mehrmalige Aufrufe von ConfigureEndpointDefaults ersetzen vorherige Instanzen von Action mit der zuletzt angegebenen Action:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });
});

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureEndpointDefaults erstellt werden, werden die Standardwerte nicht angewendet.

Configure(IConfiguration)

Ermöglicht es Kestrel, Endpunkte von einem IConfiguration zu laden. Die Konfiguration muss auf den Konfigurationsabschnitt für Kestrel festgelegt werden. Mit der Configure(IConfiguration, bool)-Überladung wird ein erneutes Laden von Endpunkten möglich, wenn sich die Konfigurationsquelle ändert.

Standardmäßig wird die Kestrel-Konfiguration aus dem Abschnitt Kestrel geladen, wobei das erneute Laden von Änderungen aktiviert ist:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}

Wenn die Konfiguration zum erneuten Laden aktiviert ist und eine Änderung signalisiert wird, werden die folgenden Schritte ausgeführt:

Die neue Konfiguration wird mit der alten verglichen, und Endpunkte ohne Konfigurationsänderungen werden nicht geändert.
Entfernte oder geänderte Endpunkte erhalten 5 Sekunden, um die Verarbeitung von Anforderungen abzuschließen und herunterzufahren.
Neue oder geänderte Endpunkte werden gestartet.

Clients, die eine Verbindung mit einem geänderten Endpunkt herstellen, werden möglicherweise getrennt oder abgelehnt, wenn der Endpunkt neu gestartet wird.

ConfigureHttpsDefaults

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) Gibt die Konfiguration Action zum Ausführen von jedem HTTPS-Endpunkt an. Mehrmalige Aufrufe von ConfigureHttpsDefaults ersetzen vorherige Instanzen von Action mit der zuletzt angegebenen Action.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureHttpsDefaults erstellt werden, werden die Standardwerte nicht angewendet.

ListenOptions.UseHttps

Konfiguriert Kestrel zur Verwendung von HTTPS.

ListenOptions.UseHttps-Erweiterungen:

UseHttps: Hiermit wird Kestrel zur Verwendung von HTTPS mit dem Standardzertifikat konfiguriert. Löst eine Ausnahme aus, wenn kein Standardzertifikat konfiguriert ist.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

ListenOptions.UseHttps-Parameter:

filename entspricht dem Pfad und Dateinamen einer Zertifikatdatei relativ zu dem Verzeichnis, das die Inhaltsdateien der App enthält.
password ist das für den Zugriff auf die X.509-Zertifikatsdaten erforderliche Kennwort.
configureOptions ist eine Action zum Konfigurieren von HttpsConnectionAdapterOptions. Gibt ListenOptions zurück.
storeName ist der Zertifikatspeicher, aus dem das Zertifikat geladen wird.
subject ist der Name des Antragstellers für das Zertifikat.
allowInvalid gibt an, ob ungültige Zertifikate berücksichtigt werden sollten, z.B. selbstsignierte Zertifikate.
location ist der Speicherort, aus dem das Zertifikat geladen wird.
serverCertificate ist das X.509-Zertifikat.

In der Produktion muss HTTPS explizit konfiguriert sein. Zumindest muss ein Standardzertifikat angegeben werden.

Wenn Zertifikate von einem Datenträger und nicht aus einem Windows-Zertifikatspeicher gelesen werden, muss das enthaltende Verzeichnis über entsprechende Berechtigungen verfügen, um nicht autorisierten Zugriff zu verhindern.

Die im Folgenden beschriebenen unterstützten Konfigurationen:

Keine Konfiguration
Ersetzen des Standardzertifikats aus der Konfiguration
Ändern des Standards im Code

Keine Konfiguration

Kestrel hört auf http://localhost:5000.

Ersetzen des Standardzertifikats aus der Konfiguration

Im folgenden Beispiel für appsettings.json gilt:

Legen Sie AllowInvalid auf true fest, um die Verwendung von ungültigen Zertifikaten zu erlauben (z.B. selbstsignierte Zertifikate).
Jeder HTTPS-Endpunkt, der kein Zertifikat angibt (im folgenden Beispiel HttpsDefaultCert), greift auf das unter Certificates:Default festgelegte Zertifikat oder das Entwicklungszertifikat zurück.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Warnung

Im vorherigen Beispiel werden Zertifikatkennwörter als Klartext in appsettings.json gespeichert. Das Token $CREDENTIAL_PLACEHOLDER$ dient als Platzhalter für das Kennwort jedes Zertifikats. Informationen zum sicheren Speichern von Zertifikatkennwörtern in Entwicklungsumgebungen finden Sie unter Schützen von Geheimnissen in der Entwicklung. Informationen zum sicheren Speichern von Zertifikatkennwörtern in Produktionsumgebungen finden Sie unter Azure Key Vault-Konfigurationsanbieter. Entwicklungsgeheimnisse sollten nicht in Produktions- oder Testumgebungen verwendet werden.

Schema-Hinweise:

Bei den Namen der Endpunkte wird die Groß-/Kleinschreibung nicht beachtet. HTTPS and Https gleichwertig.
Der Parameter Url ist für jeden Endpunkt erforderlich. Das Format für diesen Parameter ist identisch mit dem allgemeinen Konfigurationsparameter Urls, mit der Ausnahme, dass er auf einen einzelnen Wert begrenzt ist.
Diese Endpunkte ersetzen die in der allgemeinen Urls-Konfiguration festgelegten Endpunkte, anstatt zu ihnen hinzuzufügen. Endpunkte, die über Listen in Code definiert werden, werden den im Konfigurationsabschnitt definierten Endpunkten hinzugefügt.
Der Certificate-Abschnitt ist optional. Wenn der Certificate-Abschnitt nicht angegeben ist, werden die in Certificates:Default definierten Standardwerte verwendet. Wenn keine Standardwerte verfügbar sind, wird das Entwicklungszertifikat verwendet. Wenn weder Standardwerte noch Entwicklungszertifikat vorhanden sind, löst der Server eine Ausnahme aus und kann nicht gestartet werden.
Der Certificate-Abschnitt unterstützt mehrere Zertifikatquellen.
In Konfiguration kann eine beliebige Anzahl von Endpunkten definiert werden, solange sie keine Portkonflikte verursachen.

Zertifikatquellen

Zertifikatknoten können so konfiguriert werden, dass Zertifikate aus einer Reihe von Quellen geladen werden:

Path und Password zum Laden von .pfx-Dateien.
Path, KeyPath und Password zum Laden von .pem/.crt- und .key-Dateien.
Subject und Store zum Laden aus dem Zertifikatspeicher.

Das Zertifikat unter Certificates:Default kann beispielweise wie folgt angegeben werden:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

ConfigurationLoader

Configure(IConfiguration) gibt KestrelConfigurationLoader mit der Methode Endpoint(String, Action<EndpointConfiguration>) zurück, die dazu verwendet werden kann, die Einstellungen eines Endpunkts zu ergänzen:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    var kestrelSection = context.Configuration.GetSection("Kestrel");

    serverOptions.Configure(kestrelSection)
        .Endpoint("HTTPS", listenOptions =>
        {
            // ...
        });
});

Der Konfigurationsabschnitt ist für jeden Endpunkt in den Optionen der Methode Endpoint verfügbar, sodass benutzerdefinierte Einstellungen gelesen werden können.
Mehrere Konfigurationen können durch erneutes Aufrufen von Configure(IConfiguration) mit einem anderen Abschnitt geladen werden. Sofern Load nicht in einer vorherigen Instanz explizit aufgerufen wird, wird nur die letzte Konfiguration verwendet. Das Metapaket ruft Load nicht auf, sodass der Abschnitt mit der Standardkonfiguration ersetzt werden kann.
KestrelConfigurationLoader spiegelt die API-Familie Listen von KestrelServerOptions als Endpoint-Überladungen, weshalb Code und Konfigurationsendpunkte am selben Ort konfiguriert werden können. Diese Überladungen verwenden keine Namen und nutzen nur Standardeinstellungen aus der Konfiguration.

Ändern des Standards im Code

ConfigureEndpointDefaults und ConfigureHttpsDefaults können zum Ändern der Standardeinstellungen für ListenOptions und HttpsConnectionAdapterOptions verwendet werden, einschließlich der Standardzertifikate, die im vorherigen Szenario festgelegt wurden. ConfigureEndpointDefaults und ConfigureHttpsDefaults sollten aufgerufen werden, bevor Endpunkte konfiguriert werden.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Konfigurieren von Endpunkten mithilfe der Servernamensanzeige

Die Servernamensanzeige (SNI) kann zum Hosten mehrerer Domänen auf der gleichen IP-Adresse und dem gleichen Port verwendet werden. Damit die Servernamensanzeige funktioniert, sendet der Client während des TLS-Handshakes den Hostnamen für die sichere Sitzung an den Server, sodass der Server das richtige Zertifikat bereitstellen kann. Der Client verwendet das beigestellte Zertifikat für die verschlüsselte Kommunikation mit dem Server während der sicheren Sitzung nach dem TLS-Handshake.

SNI kann in zwei Varianten konfiguriert werden:

Erstellen Sie einen Endpunkt im Code, und wählen Sie ein Zertifikat mit dem Hostnamen und dem ServerCertificateSelector-Rückruf aus.
Konfigurieren Sie in der Konfiguration eine Zuordnung zwischen Hostnamen und HTTPS-Optionen. Beispiel: JSON in der appsettings.json-Datei.

SNI mit `ServerCertificateSelector`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase)
            {
                ["localhost"] = localhostCert,
                ["example.com"] = exampleCert,
                ["sub.example.com"] = subExampleCert
            };

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name is not null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI mit `ServerOptionsSelectionCallback`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost",
                    StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = localhostCert,
                            // Different TLS requirements for this host
                            ClientCertificateRequired = true
                        });
                }

                return new ValueTask<SslServerAuthenticationOptions>(
                    new SslServerAuthenticationOptions
                    {
                        ServerCertificate = exampleCert
                    });
            }, state: null!);
        });
    });
});

SNI mit `TlsHandshakeCallbackOptions`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps(new TlsHandshakeCallbackOptions
            {
                OnConnection = context =>
                {
                    if (string.Equals(context.ClientHelloInfo.ServerName, "localhost",
                        StringComparison.OrdinalIgnoreCase))
                    {
                        // Different TLS requirements for this host
                        context.AllowDelayedClientCertificateNegotation = true;

                        return new ValueTask<SslServerAuthenticationOptions>(
                            new SslServerAuthenticationOptions
                            {
                                ServerCertificate = localhostCert
                            });
                    }

                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = exampleCert
                        });
                }
            });
        });
    });
});

SNI in der Konfiguration

Die folgende Konfiguration fügt einen Endpunkt namens MySniEndpoint hinzu, der SNI verwendet, um HTTPS-Optionen basierend auf dem Hostnamen auszuwählen:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Warnung

HTTPS-Optionen, die von SNI überschrieben werden können:

Certificate konfiguriert die Zertifikatquelle.
Protocols konfiguriert die zulässigen HTTP-Protokolle.
SslProtocols konfiguriert die zulässigen SSL-Protokolle.
ClientCertificateMode konfiguriert die Clientzertifikatanforderungen.

Der Hostname unterstützt Platzhalterabgleiche:

Genaue Übereinstimmung. Beispielsweise entspricht a.example.orga.example.org.
Platzhalterpräfix. Wenn es mehrere Platzhalterübereinstimmungen gibt, wird das längste Muster ausgewählt. Beispielsweise entspricht *.example.orgb.example.org und c.example.org.
Vollständiger Platzhalter. * entspricht allem anderen, einschließlich Clients, die SNI nicht verwenden und keinen Hostnamen senden.

SNI-Anforderungen

Alle Websites müssen in derselben Kestrel-Instanz ausgeführt werden. Kestrel unterstützt ohne Reverseproxy keine gemeinsame IP-Adresse und keinen gemeinsamen Port für mehrere Instanzen.

SSL/TLS-Protokolle

SSL-Protokolle werden zum Verschlüsseln und Entschlüsseln von Datenverkehr zwischen zwei Peers verwendet werden, üblicherweise ein Client und ein Server.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Warnung

Clientzertifikate

ClientCertificateMode konfiguriert die Clientzertifikatanforderungen.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Warnung

Der Standardwert ist ClientCertificateMode.NoCertificate, wobei Kestrel kein Zertifikat vom Client anfordert oder verlangt.

Weitere Informationen finden Sie unter Konfigurieren der Zertifikatauthentifizierung in ASP.NET Core.

Verbindungsprotokollierung

Rufen Sie UseConnectionLogging auf, um Protokolle auf Debugebene für die Kommunikation auf Byteebene für eine Verbindung auszugeben. Die Verbindungsprotokollierung ist beim Beheben von Problemen bei der Low-Level-Kommunikation hilfreich, wie z. B. bei der TLS-Verschlüsselung und bei Proxys. Wenn UseConnectionLogging vor UseHttps platziert wird, wird der verschlüsselte Datenverkehr protokolliert. Wenn UseConnectionLogging nach UseHttps platziert wird, wird der entschlüsselte Datenverkehr protokolliert. Hierbei handelt es sich um integrierte Verbindungsmiddleware.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Binden an einen TCP-Socket

Die Listen-Methode wird an ein TCP-Socket gebunden, und ein Lambdaausdruck einer Option lässt die Konfiguration des X.509-Zertifikats zu:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Im Beispiel wird HTTPS für einen Endpunkt mit ListenOptions konfiguriert. Verwenden Sie die gleiche API zum Konfigurieren anderer Kestrel-Einstellungen für bestimmte Endpunkte.

Unter macOS, Linux und Windows können Zertifikate mithilfe von OpenSSL erstellt werden.

Binden an einen Unix-Socket

Wie in diesem Beispiel dargestellt, lauschen Sie an einem Unix-Socket mit ListenUnixSocket, um eine verbesserte Leistung mit Nginx zu erzielen:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
});

Legen Sie den Eintrag server>location>proxy_pass in der Nginx-Konfigurationsdatei auf http://unix:/tmp/{KESTREL SOCKET}:/; fest. {KESTREL SOCKET} ist der Name des für ListenUnixSocket bereitgestellten Socket (zum Beispiel kestrel-test.sock im vorherigen Beispiel).
Stellen Sie sicher, dass der Socket von Nginx beschreibbar ist (z. B. chmod go+w /tmp/kestrel-test.sock).

Port 0

app.Run(async (context) =>
{
    var serverAddressFeature = context.Features.Get<IServerAddressesFeature>();

    if (serverAddressFeature is not null)
    {
        var listenAddresses = string.Join(", ", serverAddressFeature.Addresses);

        // ...
    }
});

Das dynamische Binden eines Ports ist in einigen Situationen nicht verfügbar:

ListenLocalhost
Binden von TCP-basiertem HTTP/1.1 oder HTTP/2 mit QUIC-basiertem HTTP/3.

Einschränkungen

Konfigurieren Sie Endpunkte mithilfe der folgenden Ansätze:

UseUrls
Befehlszeilenargument --urls
Hostkonfigurationsschlüssel urls
Umgebungsvariable ASPNETCORE_URLS

Diese Methoden sind nützlich, wenn Ihr Code mit anderen Servern als Kestrel funktionieren soll. Beachten Sie jedoch die folgenden Einschränkungen:

HTTPS kann nicht mit diesen Ansätzen verwendet werden, außer ein Standardzertifikat wird in der HTTPS-Endpunktkonfiguration angegeben (z. B. wenn Sie wie zuvor in diesem Artikel gezeigt die KestrelServerOptions-Konfiguration oder eine Konfigurationsdatei verwenden).
Wenn die Ansätze Listen und UseUrls gleichzeitig verwendet werden, überschreiben die Listen-Endpunkte die UseUrls-Endpunkte.

IIS-Endpunktkonfiguration

Bei der Verwendung von IIS werden die URL-Bindungen für IIS-Überschreibungsbindungen durch Listen oder UseUrls festgelegt. Weitere Informationen finden Sie unter ASP.NET Core Module (ASP.NET Core-Modul).

ListenOptions.Protocols

Die Protocols-Eigenschaft richtet die HTTP-Protokolle (HttpProtocols) ein, die für einen Verbindungsendpunkt oder für den Server aktiviert werden. Weisen Sie der Protocols-Eigenschaft einen Wert aus der HttpProtocols-Enumeration zu.

`HttpProtocols`-Enumerationswert	Zulässiges Verbindungsprotokoll
`Http1`	Nur HTTP/1.1. Kann mit oder ohne TLS verwendet werden.
`Http2`	Nur HTTP/2. Kann nur ohne TLS verwendet werden, wenn der Client einen Vorabkenntnis-Modus unterstützt.
`Http3`	Nur HTTP/3 Erfordert TLS Der Client muss möglicherweise für die ausschließliche Verwendung von HTTP/3 konfiguriert werden.
`Http1AndHttp2`	HTTP/1.1 und HTTP/2. Für HTTP/2 muss der Client HTTP/2 im TLS ALPN-Handshake (Application-Layer Protocol Negotiation) auswählen, andernfalls wird standardmäßig eine HTTP/1.1 verwendet.
`Http1AndHttp2AndHttp3`	HTTP/1.1, HTTP/2 und HTTP/3. Die erste Clientanforderung verwendet normalerweise HTTP/1.1 oder HTTP/2, und der `alt-svc`-Antwortheader fordert den Client auf, ein Upgrade auf HTTP/3 durchzuführen. HTTP/2 und HTTP/3 erfordern TLS. Andernfalls wird für die Verbindung standardmäßig HTTP/1.1 verwendet.

Der Standardwert von ListenOptions.Protocols ist für alle Endpunkte HttpProtocols.Http1AndHttp2.

TLS-Einschränkungen für HTTP/2:

TLS Version 1.2 oder höher
Erneute Aushandlung deaktiviert
Komprimierung deaktiviert
Minimale Größen für Austausch von flüchtigen Schlüsseln:
- ECDHE (Elliptic Curve Diffie-Hellman) [RFC4492]: mindestens 224 Bit
- DHE (Finite Field Diffie-Hellman) [TLS12]: mindestens 2048 Bit
Verschlüsselungssammlung nicht verboten

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] mit der elliptischen P-256-Kurve [FIPS186] wird standardmäßig unterstützt.

Das folgende Beispiel erlaubt HTTP/1.1- und HTTP/2-Verbindungen an Port 8000. Die Verbindungen werden durch TLS mit einem bereitgestellten Zertifikat geschützt:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
    });
});

Unter Linux kann CipherSuitesPolicy zum Filtern von TLS-Handshakes auf Verbindungsbasis verwendet werden:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Verbindungsmiddleware

Benutzerdefinierte Verbindungsmiddleware kann bei Bedarf TLS-Handshakes auf Verbindungsbasis für bestimmte Verschlüsselungsverfahren filtern.

Im folgenden Beispiel wird NotSupportedException für jeden Verschlüsselungsalgorithmus ausgelöst, der von der App nicht unterstützt wird. Alternativ können Sie ITlsHandshakeFeature.CipherAlgorithm definieren und mit einer Liste zulässiger Verschlüsselungssammlungen vergleichen.

Keine Verschlüsselung wird mit einem Algorithmus eines CipherAlgorithmType.Null-Verschlüsselungsverfahrens verwendet.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");

        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>()!;

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Festlegen des HTTP-Protokolls in der Konfiguration

Standardmäßig wird die Kestrel-Konfiguration aus dem Abschnitt Kestrel geladen. Das folgende appsettings.json -Beispiel richtet HTTP/1.1 als Standardverbindungsprotokoll für alle Endpunkte ein:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Das folgende appsettings.json -Beispiel richtet HTTP/1.1 als Verbindungsprotokoll für einen bestimmten Endpunkt ein:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokolle, die in Code angegeben werden, setzen Werte außer Kraft, der durch die Konfiguration festgelegt werden.

URL-Präfixe

Bei der Verwendung von UseUrls, dem Befehlszeilenargument --urls, dem Hostkonfigurationsschlüssel urls oder der Umgebungsvariable ASPNETCORE_URLS können die URL-Präfixe in den folgenden Formaten vorliegen.

Nur HTTP-URL-Präfixe sind gültig. Kestrel unterstützt HTTPS nicht beim Konfigurieren von URL-Bindungen mit UseUrls.

IPv4-Adresse mit Portnummer
```
http://65.55.39.10:80/
```
Bei 0.0.0.0 handelt es sich um einen Sonderfall, für den eine Bindung an alle IPv4-Adressen erfolgt.
IPv6-Adresse mit Portnummer
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] stellt das Äquivalent von IPv6 zu 0.0.0.0 für IPv4 dar.
Hostname mit Portnummer
```
http://contoso.com:80/
http://*:80/
```
Hostnamen, * und + sind nicht spezifisch. Alle Elemente, die nicht als gültige IP-Adresse oder localhost erkannt werden, werden an alle IPv4- und IPv6-IP-Adressen gebunden. Verwenden Sie HTTP.sys oder einen Reverseproxyserver zum Binden verschiedener Hostnamen an verschiedene ASP.NET Core-Apps auf demselben Port. Beispiele für Reverseproxyserver sind IIS, Nginx oder Apache.

Warnung

Das Hosting in einer Reverseproxykonfiguration erfordert Hostfilterung.
localhost-Hostname mit Portnummer oder Loopback-IP mit Portnummer
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Wenn localhost angegeben ist, versucht Kestrel, eine Bindung zu IPv4- und IPv6-Loopback-Schnittstellen zu erstellen. Wenn der erforderliche Port von einem anderen Dienst auf einer der Loopback-Schnittstellen verwendet wird, tritt beim Starten von Kestrel ein Fehler auf. Wenn eine der Loopback-Schnittstellen aus anderen Gründen nicht verfügbar ist (meistens durch die fehlende Unterstützung von IPv6), protokolliert Kestrel eine Warnung.

http://localhost:5000
https://localhost:5001 (wenn ein lokales Entwicklungszertifikat vorhanden ist)

Verwenden Sie Folgendes zum Angeben der URLs:

Die Umgebungsvariable ASPNETCORE_URLS
Das Befehlszeilenargument --urls
Den Hostkonfigurationsschlüssel urls
Die Erweiterungsmethode UseUrls

Weitere Informationen zu diesen Ansätzen finden Sie unter Server-URLs und Außerkraftsetzen der Konfiguration.

Ein Entwicklungszertifikat wird erstellt:

Bei Installation des .NET SDK
Das dev-cert-Tool wird zum Erstellen eines Zertifikats verwendet.

Projektvorlagen konfigurieren Apps, damit sie standardmäßig auf HTTPS ausgeführt werden und die HTTPS-Umleitung und HSTS-Unterstützung enthalten.

Rufen Sie die Listen- oder ListenUnixSocket-Methode unter KestrelServerOptions auf, um URL-Präfixe und Ports für Kestrel zu konfigurieren.

KestrelServerOptions-Konfiguration:

ConfigureEndpointDefaults

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });
});

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureEndpointDefaults erstellt werden, werden die Standardwerte nicht angewendet.

Configure(IConfiguration)

Standardmäßig wird die Kestrel-Konfiguration aus dem Abschnitt Kestrel geladen, wobei das erneute Laden von Änderungen aktiviert ist:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}

Wenn die Konfiguration zum erneuten Laden aktiviert ist und eine Änderung signalisiert wird, werden die folgenden Schritte ausgeführt:

Die neue Konfiguration wird mit der alten verglichen, und Endpunkte ohne Konfigurationsänderungen werden nicht geändert.
Entfernte oder geänderte Endpunkte erhalten 5 Sekunden, um die Verarbeitung von Anforderungen abzuschließen und herunterzufahren.
Neue oder geänderte Endpunkte werden gestartet.

Clients, die eine Verbindung mit einem geänderten Endpunkt herstellen, werden möglicherweise getrennt oder abgelehnt, wenn der Endpunkt neu gestartet wird.

ConfigureHttpsDefaults

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureHttpsDefaults erstellt werden, werden die Standardwerte nicht angewendet.

ListenOptions.UseHttps

Konfiguriert Kestrel zur Verwendung von HTTPS.

ListenOptions.UseHttps-Erweiterungen:

UseHttps: Hiermit wird Kestrel zur Verwendung von HTTPS mit dem Standardzertifikat konfiguriert. Löst eine Ausnahme aus, wenn kein Standardzertifikat konfiguriert ist.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

ListenOptions.UseHttps-Parameter:

filename entspricht dem Pfad und Dateinamen einer Zertifikatdatei relativ zu dem Verzeichnis, das die Inhaltsdateien der App enthält.
password ist das für den Zugriff auf die X.509-Zertifikatsdaten erforderliche Kennwort.
configureOptions ist eine Action zum Konfigurieren von HttpsConnectionAdapterOptions. Gibt ListenOptions zurück.
storeName ist der Zertifikatspeicher, aus dem das Zertifikat geladen wird.
subject ist der Name des Antragstellers für das Zertifikat.
allowInvalid gibt an, ob ungültige Zertifikate berücksichtigt werden sollten, z.B. selbstsignierte Zertifikate.
location ist der Speicherort, aus dem das Zertifikat geladen wird.
serverCertificate ist das X.509-Zertifikat.

In der Produktion muss HTTPS explizit konfiguriert sein. Zumindest muss ein Standardzertifikat angegeben werden.

Die im Folgenden beschriebenen unterstützten Konfigurationen:

Keine Konfiguration
Ersetzen des Standardzertifikats aus der Konfiguration
Ändern des Standards im Code

Keine Konfiguration

Kestrel überwacht http://localhost:5000 und https://localhost:5001 (wenn ein Standardzertifikat verfügbar ist).

Ersetzen des Standardzertifikats aus der Konfiguration

Im folgenden Beispiel für appsettings.json gilt:

Legen Sie AllowInvalid auf true fest, um die Verwendung von ungültigen Zertifikaten zu erlauben (z.B. selbstsignierte Zertifikate).
Jeder HTTPS-Endpunkt, der kein Zertifikat angibt (im folgenden Beispiel HttpsDefaultCert), greift auf das unter Certificates:Default festgelegte Zertifikat oder das Entwicklungszertifikat zurück.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Warnung

Schema-Hinweise:

Bei den Namen der Endpunkte wird die Groß-/Kleinschreibung nicht beachtet. HTTPS and Https gleichwertig.
Der Parameter Url ist für jeden Endpunkt erforderlich. Das Format für diesen Parameter ist identisch mit dem allgemeinen Konfigurationsparameter Urls, mit der Ausnahme, dass er auf einen einzelnen Wert begrenzt ist.
Diese Endpunkte ersetzen die in der allgemeinen Urls-Konfiguration festgelegten Endpunkte, anstatt zu ihnen hinzuzufügen. Endpunkte, die über Listen in Code definiert werden, werden den im Konfigurationsabschnitt definierten Endpunkten hinzugefügt.
Der Certificate-Abschnitt ist optional. Wenn der Certificate-Abschnitt nicht angegeben ist, werden die in Certificates:Default definierten Standardwerte verwendet. Wenn keine Standardwerte verfügbar sind, wird das Entwicklungszertifikat verwendet. Wenn weder Standardwerte noch Entwicklungszertifikat vorhanden sind, löst der Server eine Ausnahme aus und kann nicht gestartet werden.
Der Certificate-Abschnitt unterstützt mehrere Zertifikatquellen.
In Konfiguration kann eine beliebige Anzahl von Endpunkten definiert werden, solange sie keine Portkonflikte verursachen.

Zertifikatquellen

Zertifikatknoten können so konfiguriert werden, dass Zertifikate aus einer Reihe von Quellen geladen werden:

Path und Password zum Laden von .pfx-Dateien.
Path, KeyPath und Password zum Laden von .pem/.crt- und .key-Dateien.
Subject und Store zum Laden aus dem Zertifikatspeicher.

Das Zertifikat unter Certificates:Default kann beispielweise wie folgt angegeben werden:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

ConfigurationLoader

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    var kestrelSection = context.Configuration.GetSection("Kestrel");

    serverOptions.Configure(kestrelSection)
        .Endpoint("HTTPS", listenOptions =>
        {
            // ...
        });
});

Der Konfigurationsabschnitt ist für jeden Endpunkt in den Optionen der Methode Endpoint verfügbar, sodass benutzerdefinierte Einstellungen gelesen werden können.
Mehrere Konfigurationen können durch erneutes Aufrufen von Configure(IConfiguration) mit einem anderen Abschnitt geladen werden. Sofern Load nicht in einer vorherigen Instanz explizit aufgerufen wird, wird nur die letzte Konfiguration verwendet. Das Metapaket ruft Load nicht auf, sodass der Abschnitt mit der Standardkonfiguration ersetzt werden kann.
KestrelConfigurationLoader spiegelt die API-Familie Listen von KestrelServerOptions als Endpoint-Überladungen, weshalb Code und Konfigurationsendpunkte am selben Ort konfiguriert werden können. Diese Überladungen verwenden keine Namen und nutzen nur Standardeinstellungen aus der Konfiguration.

Ändern des Standards im Code

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // ...
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // ...
    });
});

Konfigurieren von Endpunkten mithilfe der Servernamensanzeige

SNI kann in zwei Varianten konfiguriert werden:

Erstellen Sie einen Endpunkt im Code, und wählen Sie ein Zertifikat mit dem Hostnamen und dem ServerCertificateSelector-Rückruf aus.
Konfigurieren Sie in der Konfiguration eine Zuordnung zwischen Hostnamen und HTTPS-Optionen. Beispiel: JSON in der appsettings.json-Datei.

SNI mit `ServerCertificateSelector`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(
                StringComparer.OrdinalIgnoreCase)
            {
                ["localhost"] = localhostCert,
                ["example.com"] = exampleCert,
                ["sub.example.com"] = subExampleCert
            };

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name is not null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI mit `ServerOptionsSelectionCallback`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost",
                    StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = localhostCert,
                            // Different TLS requirements for this host
                            ClientCertificateRequired = true
                        });
                }

                return new ValueTask<SslServerAuthenticationOptions>(
                    new SslServerAuthenticationOptions
                    {
                        ServerCertificate = exampleCert
                    });
            }, state: null!);
        });
    });
});

SNI mit `TlsHandshakeCallbackOptions`

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps(new TlsHandshakeCallbackOptions
            {
                OnConnection = context =>
                {
                    if (string.Equals(context.ClientHelloInfo.ServerName, "localhost",
                        StringComparison.OrdinalIgnoreCase))
                    {
                        // Different TLS requirements for this host
                        context.AllowDelayedClientCertificateNegotation = true;

                        return new ValueTask<SslServerAuthenticationOptions>(
                            new SslServerAuthenticationOptions
                            {
                                ServerCertificate = localhostCert
                            });
                    }

                    return new ValueTask<SslServerAuthenticationOptions>(
                        new SslServerAuthenticationOptions
                        {
                            ServerCertificate = exampleCert
                        });
                }
            });
        });
    });
});

SNI in der Konfiguration

Die folgende Konfiguration fügt einen Endpunkt namens MySniEndpoint hinzu, der SNI verwendet, um HTTPS-Optionen basierend auf dem Hostnamen auszuwählen:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Warnung

HTTPS-Optionen, die von SNI überschrieben werden können:

Certificate konfiguriert die Zertifikatquelle.
Protocols konfiguriert die zulässigen HTTP-Protokolle.
SslProtocols konfiguriert die zulässigen SSL-Protokolle.
ClientCertificateMode konfiguriert die Clientzertifikatanforderungen.

Der Hostname unterstützt Platzhalterabgleiche:

Genaue Übereinstimmung. Beispielsweise entspricht a.example.orga.example.org.
Platzhalterpräfix. Wenn es mehrere Platzhalterübereinstimmungen gibt, wird das längste Muster ausgewählt. Beispielsweise entspricht *.example.orgb.example.org und c.example.org.
Vollständiger Platzhalter. * entspricht allem anderen, einschließlich Clients, die SNI nicht verwenden und keinen Hostnamen senden.

SNI-Anforderungen

Alle Websites müssen in derselben Kestrel-Instanz ausgeführt werden. Kestrel unterstützt ohne Reverseproxy keine gemeinsame IP-Adresse und keinen gemeinsamen Port für mehrere Instanzen.

SSL/TLS-Protokolle

SSL-Protokolle werden zum Verschlüsseln und Entschlüsseln von Datenverkehr zwischen zwei Peers verwendet werden, üblicherweise ein Client und ein Server.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Warnung

Clientzertifikate

ClientCertificateMode konfiguriert die Clientzertifikatanforderungen.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Warnung

Der Standardwert ist ClientCertificateMode.NoCertificate, wobei Kestrel kein Zertifikat vom Client anfordert oder verlangt.

Weitere Informationen finden Sie unter Konfigurieren der Zertifikatauthentifizierung in ASP.NET Core.

Verbindungsprotokollierung

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Binden an einen TCP-Socket

Die Listen-Methode wird an ein TCP-Socket gebunden, und ein Lambdaausdruck einer Option lässt die Konfiguration des X.509-Zertifikats zu:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Loopback, 5000);
    serverOptions.Listen(IPAddress.Loopback, 5001, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Im Beispiel wird HTTPS für einen Endpunkt mit ListenOptions konfiguriert. Verwenden Sie die gleiche API zum Konfigurieren anderer Kestrel-Einstellungen für bestimmte Endpunkte.

Unter macOS, Linux und Windows können Zertifikate mithilfe von OpenSSL erstellt werden.

Binden an einen Unix-Socket

Wie in diesem Beispiel dargestellt, lauschen Sie an einem Unix-Socket mit ListenUnixSocket, um eine verbesserte Leistung mit Nginx zu erzielen:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
});

Legen Sie den Eintrag server>location>proxy_pass in der Nginx-Konfigurationsdatei auf http://unix:/tmp/{KESTREL SOCKET}:/; fest. {KESTREL SOCKET} ist der Name des für ListenUnixSocket bereitgestellten Socket (zum Beispiel kestrel-test.sock im vorherigen Beispiel).
Stellen Sie sicher, dass der Socket von Nginx beschreibbar ist (z. B. chmod go+w /tmp/kestrel-test.sock).

Port 0

app.Run(async (context) =>
{
    var serverAddressFeature = context.Features.Get<IServerAddressesFeature>();

    if (serverAddressFeature is not null)
    {
        var listenAddresses = string.Join(", ", serverAddressFeature.Addresses);

        // ...
    }
});

Einschränkungen

Konfigurieren Sie Endpunkte mithilfe der folgenden Ansätze:

UseUrls
Befehlszeilenargument --urls
Hostkonfigurationsschlüssel urls
Umgebungsvariable ASPNETCORE_URLS

Diese Methoden sind nützlich, wenn Ihr Code mit anderen Servern als Kestrel funktionieren soll. Beachten Sie jedoch die folgenden Einschränkungen:

HTTPS kann nicht mit diesen Ansätzen verwendet werden, außer ein Standardzertifikat wird in der HTTPS-Endpunktkonfiguration angegeben (z. B. wenn Sie wie zuvor in diesem Artikel gezeigt die KestrelServerOptions-Konfiguration oder eine Konfigurationsdatei verwenden).
Wenn die Ansätze Listen und UseUrls gleichzeitig verwendet werden, überschreiben die Listen-Endpunkte die UseUrls-Endpunkte.

IIS-Endpunktkonfiguration

ListenOptions.Protocols

`HttpProtocols`-Enumerationswert	Zulässiges Verbindungsprotokoll
`Http1`	Nur HTTP/1.1. Kann mit oder ohne TLS verwendet werden.
`Http2`	Nur HTTP/2. Kann nur ohne TLS verwendet werden, wenn der Client einen Vorabkenntnis-Modus unterstützt.
`Http1AndHttp2`	HTTP/1.1 und HTTP/2. Für HTTP/2 muss der Client HTTP/2 im TLS ALPN-Handshake (Application-Layer Protocol Negotiation) auswählen, andernfalls wird standardmäßig eine HTTP/1.1 verwendet.

Der Standardwert von ListenOptions.Protocols ist für alle Endpunkte HttpProtocols.Http1AndHttp2.

TLS-Einschränkungen für HTTP/2:

TLS Version 1.2 oder höher
Erneute Aushandlung deaktiviert
Komprimierung deaktiviert
Minimale Größen für Austausch von flüchtigen Schlüsseln:
- ECDHE (Elliptic Curve Diffie-Hellman) [RFC4492]: mindestens 224 Bit
- DHE (Finite Field Diffie-Hellman) [TLS12]: mindestens 2048 Bit
Verschlüsselungssammlung nicht verboten

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] mit der elliptischen P-256-Kurve [FIPS186] wird standardmäßig unterstützt.

Das folgende Beispiel erlaubt HTTP/1.1- und HTTP/2-Verbindungen an Port 8000. Die Verbindungen werden durch TLS mit einem bereitgestellten Zertifikat geschützt:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Protocols = HttpProtocols.Http1AndHttp2AndHttp3;
    });
});

Unter Linux kann CipherSuitesPolicy zum Filtern von TLS-Handshakes auf Verbindungsbasis verwendet werden:

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Verbindungsmiddleware

Benutzerdefinierte Verbindungsmiddleware kann bei Bedarf TLS-Handshakes auf Verbindungsbasis für bestimmte Verschlüsselungsverfahren filtern.

Keine Verschlüsselung wird mit einem Algorithmus eines CipherAlgorithmType.Null-Verschlüsselungsverfahrens verwendet.

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.ConfigureKestrel((context, serverOptions) =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");

        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>()!;

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Festlegen des HTTP-Protokolls in der Konfiguration

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Das folgende appsettings.json -Beispiel richtet HTTP/1.1 als Verbindungsprotokoll für einen bestimmten Endpunkt ein:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokolle, die in Code angegeben werden, setzen Werte außer Kraft, der durch die Konfiguration festgelegt werden.

URL-Präfixe

Nur HTTP-URL-Präfixe sind gültig. Kestrel unterstützt HTTPS nicht beim Konfigurieren von URL-Bindungen mit UseUrls.

IPv4-Adresse mit Portnummer
```
http://65.55.39.10:80/
```
Bei 0.0.0.0 handelt es sich um einen Sonderfall, für den eine Bindung an alle IPv4-Adressen erfolgt.
IPv6-Adresse mit Portnummer
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] stellt das Äquivalent von IPv6 zu 0.0.0.0 für IPv4 dar.
Hostname mit Portnummer
```
http://contoso.com:80/
http://*:80/
```
Hostnamen, * und + sind nicht spezifisch. Alle Elemente, die nicht als gültige IP-Adresse oder localhost erkannt werden, werden an alle IPv4- und IPv6-IP-Adressen gebunden. Verwenden Sie HTTP.sys oder einen Reverseproxyserver zum Binden verschiedener Hostnamen an verschiedene ASP.NET Core-Apps auf demselben Port. Beispiele für Reverseproxyserver sind IIS, Nginx oder Apache.

Warnung

Das Hosting in einer Reverseproxykonfiguration erfordert Hostfilterung.
localhost-Hostname mit Portnummer oder Loopback-IP mit Portnummer
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Wenn localhost angegeben ist, versucht Kestrel, eine Bindung zu IPv4- und IPv6-Loopback-Schnittstellen zu erstellen. Wenn der erforderliche Port von einem anderen Dienst auf einer der Loopback-Schnittstellen verwendet wird, tritt beim Starten von Kestrel ein Fehler auf. Wenn eine der Loopback-Schnittstellen aus anderen Gründen nicht verfügbar ist (meistens durch die fehlende Unterstützung von IPv6), protokolliert Kestrel eine Warnung.

Standardmäßig wird ASP.NET Core an Folgendes gebunden:

http://localhost:5000
https://localhost:5001 (wenn ein lokales Entwicklungszertifikat vorhanden ist)

Verwenden Sie Folgendes zum Angeben der URLs:

Die Umgebungsvariable ASPNETCORE_URLS
Das Befehlszeilenargument --urls
Den Hostkonfigurationsschlüssel urls
Die Erweiterungsmethode UseUrls

Weitere Informationen zu diesen Ansätzen finden Sie unter Server-URLs und Außerkraftsetzen der Konfiguration.

Ein Entwicklungszertifikat wird erstellt:

Bei Installation des .NET SDK
Das dev-cert-Tool wird zum Erstellen eines Zertifikats verwendet.

Einige Browser erfordern, dass Sie die explizite Berechtigung erteilen, dem lokalen Entwicklungszertifikat zu vertrauen.

Projektvorlagen konfigurieren Apps, damit sie standardmäßig auf HTTPS ausgeführt werden und die HTTPS-Umleitung und HSTS-Unterstützung enthalten.

Rufen Sie die Listen- oder ListenUnixSocket-Methode unter KestrelServerOptions auf, um URL-Präfixe und Ports für Kestrel zu konfigurieren.

KestrelServerOptions-Konfiguration:

ConfigureEndpointDefaults

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });
});

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureEndpointDefaults erstellt werden, werden die Standardwerte nicht angewendet.

Configure(IConfiguration)

Ermöglicht es Kestrel, Endpunkte von einem IConfiguration zu laden. Die Konfiguration muss auf den Konfigurationsabschnitt für Kestrel festgelegt werden.

Mit der Configure(IConfiguration, bool)-Überladung wird ein erneutes Laden von Endpunkten möglich, wenn sich die Konfigurationsquelle ändert.

IHostBuilder.ConfigureWebHostDefaults ruft Configure(context.Configuration.GetSection("Kestrel"), reloadOnChange: true) standardmäßig zum Laden der Kestrel-Konfiguration auf und erlaubt ein erneutes Laden.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001"
      }
    }
  }
}

Wenn die Konfiguration zum erneuten Laden aktiviert ist und eine Änderung signalisiert wird, werden die folgenden Schritte ausgeführt:

Die neue Konfiguration wird mit der alten verglichen, und Endpunkte ohne Konfigurationsänderungen werden nicht geändert.
Entfernte oder geänderte Endpunkte erhalten 5 Sekunden, um die Verarbeitung von Anforderungen abzuschließen und herunterzufahren.
Neue oder geänderte Endpunkte werden gestartet.

Clients, die eine Verbindung mit einem geänderten Endpunkt herstellen, werden möglicherweise getrennt oder abgelehnt, wenn der Endpunkt neu gestartet wird.

ConfigureHttpsDefaults

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // certificate is an X509Certificate2
        listenOptions.ServerCertificate = certificate;
    });
});

Hinweis

Auf Endpunkte, die durch Aufrufen von Listen vor dem Aufrufen von ConfigureHttpsDefaults erstellt werden, werden die Standardwerte nicht angewendet.

ListenOptions.UseHttps

Konfiguriert Kestrel zur Verwendung von HTTPS.

ListenOptions.UseHttps-Erweiterungen:

UseHttps: Hiermit wird Kestrel zur Verwendung von HTTPS mit dem Standardzertifikat konfiguriert. Löst eine Ausnahme aus, wenn kein Standardzertifikat konfiguriert ist.
UseHttps(string fileName)
UseHttps(string fileName, string password)
UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(StoreName storeName, string subject)
UseHttps(StoreName storeName, string subject, bool allowInvalid)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(X509Certificate2 serverCertificate)
UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

ListenOptions.UseHttps-Parameter:

filename entspricht dem Pfad und Dateinamen einer Zertifikatdatei relativ zu dem Verzeichnis, das die Inhaltsdateien der App enthält.
password ist das für den Zugriff auf die X.509-Zertifikatsdaten erforderliche Kennwort.
configureOptions ist eine Action zum Konfigurieren von HttpsConnectionAdapterOptions. Gibt ListenOptions zurück.
storeName ist der Zertifikatspeicher, aus dem das Zertifikat geladen wird.
subject ist der Name des Antragstellers für das Zertifikat.
allowInvalid gibt an, ob ungültige Zertifikate berücksichtigt werden sollten, z.B. selbstsignierte Zertifikate.
location ist der Speicherort, aus dem das Zertifikat geladen wird.
serverCertificate ist das X.509-Zertifikat.

In der Produktion muss HTTPS explizit konfiguriert sein. Zumindest muss ein Standardzertifikat angegeben werden.

Die im Folgenden beschriebenen unterstützten Konfigurationen:

Keine Konfiguration
Ersetzen des Standardzertifikats aus der Konfiguration
Ändern des Standards im Code

Keine Konfiguration

Kestrel überwacht http://localhost:5000 und https://localhost:5001 (wenn ein Standardzertifikat verfügbar ist).

Ersetzen des Standardzertifikats aus der Konfiguration

Im folgenden Beispiel für appsettings.json gilt:

Legen Sie AllowInvalid auf true fest, um die Verwendung von ungültigen Zertifikaten zu erlauben (z.B. selbstsignierte Zertifikate).
Jeder HTTPS-Endpunkt, der kein Zertifikat angibt (im folgenden Beispiel HttpsDefaultCert), greift auf das unter Certificates:Default festgelegte Zertifikat oder das Entwicklungszertifikat zurück.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      },
      "HttpsInlineCertStore": {
        "Url": "https://localhost:5003",
        "Certificate": {
          "Subject": "<subject; required>",
          "Store": "<certificate store; required>",
          "Location": "<location; defaults to CurrentUser>",
          "AllowInvalid": "<true or false; defaults to false>"
        }
      },
      "HttpsDefaultCert": {
        "Url": "https://localhost:5004"
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Warnung

Schema-Hinweise:

Bei den Namen der Endpunkte wird die Groß-/Kleinschreibung nicht beachtet. HTTPS and Https gleichwertig.
Der Parameter Url ist für jeden Endpunkt erforderlich. Das Format für diesen Parameter ist identisch mit dem allgemeinen Konfigurationsparameter Urls, mit der Ausnahme, dass er auf einen einzelnen Wert begrenzt ist.
Diese Endpunkte ersetzen die in der allgemeinen Urls-Konfiguration festgelegten Endpunkte, anstatt zu ihnen hinzuzufügen. Endpunkte, die über Listen in Code definiert werden, werden den im Konfigurationsabschnitt definierten Endpunkten hinzugefügt.
Der Certificate-Abschnitt ist optional. Wenn der Certificate-Abschnitt nicht angegeben ist, werden die in Certificates:Default definierten Standardwerte verwendet. Wenn keine Standardwerte verfügbar sind, wird das Entwicklungszertifikat verwendet. Wenn weder Standardwerte noch Entwicklungszertifikat vorhanden sind, löst der Server eine Ausnahme aus und kann nicht gestartet werden.
Der Certificate-Abschnitt unterstützt mehrere Zertifikatquellen.
In Konfiguration kann eine beliebige Anzahl von Endpunkten definiert werden, solange sie keine Portkonflikte verursachen.

Zertifikatquellen

Zertifikatknoten können so konfiguriert werden, dass Zertifikate aus einer Reihe von Quellen geladen werden:

Path und Password zum Laden von .pfx-Dateien.
Path, KeyPath und Password zum Laden von .pem/.crt- und .key-Dateien.
Subject und Store zum Laden aus dem Zertifikatspeicher.

Das Zertifikat unter Certificates:Default kann beispielweise wie folgt angegeben werden:

"Default": {
  "Subject": "<subject; required>",
  "Store": "<cert store; required>",
  "Location": "<location; defaults to CurrentUser>",
  "AllowInvalid": "<true or false; defaults to false>"
}

ConfigurationLoader

options.Configure(context.Configuration.GetSection("{SECTION}")) gibt KestrelConfigurationLoader mit der Methode .Endpoint(string name, listenOptions => { }) zurück, die dazu verwendet werden kann, die Einstellungen eines Endpunkts zu ergänzen:

webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

Auf KestrelServerOptions.ConfigurationLoader kann direkt zugegriffen werden, um die Iteration auf dem vorhandenen Ladeprogramm fortzusetzen, etwa auf dem von CreateDefaultBuilder bereitgestellten Ladeprogramm.

Der Konfigurationsabschnitt ist für jeden Endpunkt in den Optionen der Methode Endpoint verfügbar, sodass benutzerdefinierte Einstellungen gelesen werden können.
Mehrere Konfigurationen können durch erneutes Aufrufen von options.Configure(context.Configuration.GetSection("{SECTION}")) mit einem anderen Abschnitt geladen werden. Sofern Load nicht in einer vorherigen Instanz explizit aufgerufen wird, wird nur die letzte Konfiguration verwendet. Das Metapaket ruft Load nicht auf, sodass der Abschnitt mit der Standardkonfiguration ersetzt werden kann.
KestrelConfigurationLoader spiegelt die API-Familie Listen von KestrelServerOptions als Endpoint-Überladungen, weshalb Code und Konfigurationsendpunkte am selben Ort konfiguriert werden können. Diese Überladungen verwenden keine Namen und nutzen nur Standardeinstellungen aus der Konfiguration.

Ändern des Standards im Code

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls12;
    });
});

Konfigurieren von Endpunkten mithilfe der Servernamensanzeige

SNI kann in zwei Varianten konfiguriert werden:

Erstellen Sie einen Endpunkt im Code, und wählen Sie ein Zertifikat mit dem Hostnamen und dem ServerCertificateSelector-Rückruf aus.
Konfigurieren Sie in der Konfiguration eine Zuordnung zwischen Hostnamen und HTTPS-Optionen. Beispiel: JSON in der appsettings.json-Datei.

SNI mit `ServerCertificateSelector`

Kestrel unterstützt die Servernamensanzeige über den ServerCertificateSelector-Rückruf. Der Rückruf wird für jede Verbindung einmal aufgerufen, um der App zu ermöglichen, den Hostnamen zu überprüfen und das entsprechende Zertifikat auszuwählen. Der folgende Rückrufcode kann im Aufruf der ConfigureWebHostDefaults-Methoden in der Datei Program.cs eines Projekts verwendet werden:

// using System.Security.Cryptography.X509Certificates;
// using Microsoft.AspNetCore.Server.Kestrel.Https;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var subExampleCert = CertificateLoader.LoadFromStoreCert(
                "sub.example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var certs = new Dictionary<string, X509Certificate2>(StringComparer.OrdinalIgnoreCase)
            {
                { "localhost", localhostCert },
                { "example.com", exampleCert },
                { "sub.example.com", subExampleCert },
            };            

            httpsOptions.ServerCertificateSelector = (connectionContext, name) =>
            {
                if (name != null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI mit `ServerOptionsSelectionCallback`

// using System.Security.Cryptography.X509Certificates;
// using Microsoft.AspNetCore.Server.Kestrel.Https;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenAnyIP(5005, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            var localhostCert = CertificateLoader.LoadFromStoreCert(
                "localhost", "My", StoreLocation.CurrentUser,
                allowInvalid: true);
            var exampleCert = CertificateLoader.LoadFromStoreCert(
                "example.com", "My", StoreLocation.CurrentUser,
                allowInvalid: true);

            listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
            {
                if (string.Equals(clientHelloInfo.ServerName, "localhost", StringComparison.OrdinalIgnoreCase))
                {
                    return new ValueTask<SslServerAuthenticationOptions>(new SslServerAuthenticationOptions
                    {
                        ServerCertificate = localhostCert,
                        // Different TLS requirements for this host
                        ClientCertificateRequired = true,
                    });
                }

                return new ValueTask<SslServerAuthenticationOptions>(new SslServerAuthenticationOptions
                {
                    ServerCertificate = exampleCert,
                });
            }, state: null);
        });
    });
});

SNI in der Konfiguration

Die folgende Konfiguration fügt einen Endpunkt namens MySniEndpoint hinzu, der SNI verwendet, um HTTPS-Optionen basierend auf dem Hostnamen auszuwählen:

{
  "Kestrel": {
    "Endpoints": {
      "MySniEndpoint": {
        "Url": "https://*",
        "SslProtocols": ["Tls11", "Tls12"],
        "Sni": {
          "a.example.org": {
            "Protocols": "Http1AndHttp2",
            "SslProtocols": ["Tls11", "Tls12", "Tls13"],
            "Certificate": {
              "Subject": "<subject; required>",
              "Store": "<certificate store; required>",
            },
            "ClientCertificateMode" : "NoCertificate"
          },
          "*.example.org": {
            "Certificate": {
              "Path": "<path to .pfx file>",
              "Password": "$CREDENTIAL_PLACEHOLDER$"
            }
          },
          "*": {
            // At least one subproperty needs to exist per SNI section or it
            // cannot be discovered via IConfiguration
            "Protocols": "Http1",
          }
        }
      }
    },
    "Certificates": {
      "Default": {
        "Path": "<path to .pfx file>",
        "Password": "$CREDENTIAL_PLACEHOLDER$"
      }
    }
  }
}

Warnung

HTTPS-Optionen, die von SNI überschrieben werden können:

Certificate konfiguriert die Zertifikatquelle.
Protocols konfiguriert die zulässigen HTTP-Protokolle.
SslProtocols konfiguriert die zulässigen SSL-Protokolle.
ClientCertificateMode konfiguriert die Clientzertifikatanforderungen.

Der Hostname unterstützt Platzhalterabgleiche:

Genaue Übereinstimmung. Beispielsweise entspricht a.example.orga.example.org.
Platzhalterpräfix. Wenn es mehrere Platzhalterübereinstimmungen gibt, wird das längste Muster ausgewählt. Beispielsweise entspricht *.example.orgb.example.org und c.example.org.
Vollständiger Platzhalter. * entspricht allem anderen, einschließlich Clients, die SNI nicht verwenden und keinen Hostnamen senden.

SNI-Anforderungen

Wird auf dem Zielframework netcoreapp2.1 oder höher ausgeführt. In net461 oder höher, wird der Rückruf aufgerufen, name ist aber immer null. name ist auch null, wenn der Client den Hostnamenparameter nicht im TLS-Handshake angibt.
Alle Websites werden in derselben Kestrel-Instanz ausgeführt. Kestrel unterstützt ohne Reverseproxy keine gemeinsame IP-Adresse und keinen gemeinsamen Port für mehrere Instanzen.

SSL/TLS-Protokolle

SSL-Protokolle werden zum Verschlüsseln und Entschlüsseln von Datenverkehr zwischen zwei Peers verwendet werden, üblicherweise ein Client und ein Server.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls13;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "SslProtocols": ["Tls12", "Tls13"],
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Warnung

Clientzertifikate

ClientCertificateMode konfiguriert die Clientzertifikatanforderungen.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.ClientCertificateMode = ClientCertificateMode.AllowCertificate;
    });
});

{
  "Kestrel": {
    "Endpoints": {
      "MyHttpsEndpoint": {
        "Url": "https://localhost:5001",
        "ClientCertificateMode": "AllowCertificate",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "$CREDENTIAL_PLACEHOLDER$"
        }
      }
    }
  }
}

Warnung

Der Standardwert ist ClientCertificateMode.NoCertificate, wobei Kestrel kein Zertifikat vom Client anfordert oder verlangt.

Weitere Informationen finden Sie unter Konfigurieren der Zertifikatauthentifizierung in ASP.NET Core.

Verbindungsprotokollierung

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Binden an einen TCP-Socket

Die Listen-Methode wird an ein TCP-Socket gebunden, und ein Lambdaausdruck einer Option lässt die Konfiguration des X.509-Zertifikats zu:

public static void Main(string[] args)
{
    CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.Listen(IPAddress.Loopback, 5000);
                serverOptions.Listen(IPAddress.Loopback, 5001, 
                    listenOptions =>
                    {
                        listenOptions.UseHttps("testCert.pfx", 
                            "testPassword");
                    });
            })
            .UseStartup<Startup>();
        });

Im Beispiel wird HTTPS für einen Endpunkt mit ListenOptions konfiguriert. Verwenden Sie die gleiche API zum Konfigurieren anderer Kestrel-Einstellungen für bestimmte Endpunkte.

Unter macOS, Linux und Windows können Zertifikate mithilfe von OpenSSL erstellt werden.

Binden an einen Unix-Socket

Wie in diesem Beispiel dargestellt, lauschen Sie an einem Unix-Socket mit ListenUnixSocket, um eine verbesserte Leistung mit Nginx zu erzielen:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})

Legen Sie den Eintrag server>location>proxy_pass in der Nginx-Konfigurationsdatei auf http://unix:/tmp/{KESTREL SOCKET}:/; fest. {KESTREL SOCKET} ist der Name des für ListenUnixSocket bereitgestellten Socket (zum Beispiel kestrel-test.sock im vorherigen Beispiel).
Stellen Sie sicher, dass der Socket von Nginx beschreibbar ist (z. B. chmod go+w /tmp/kestrel-test.sock).

Port 0

public void Configure(IApplicationBuilder app)
{
    var serverAddressesFeature =
        app.ServerFeatures.Get<IServerAddressesFeature>();

    app.UseStaticFiles();

    app.Run(async (context) =>
    {
        context.Response.ContentType = "text/html";
        await context.Response
            .WriteAsync("<!DOCTYPE html><html lang=\"en\"><head>" +
                "<title></title></head><body><p>Hosted by Kestrel</p>");

        if (serverAddressesFeature != null)
        {
            await context.Response
                .WriteAsync("<p>Listening on the following addresses: " +
                    string.Join(", ", serverAddressesFeature.Addresses) +
                    "</p>");
        }

        await context.Response.WriteAsync("<p>Request URL: " +
            $"{context.Request.GetDisplayUrl()}<p>");
    });
}

Wenn die App ausgeführt wird, gibt das Ausgabefenster der Konsole den dynamischen Port an, über den die App erreicht werden kann:

Listening on the following addresses: http://127.0.0.1:48508

Einschränkungen

Konfigurieren Sie Endpunkte mithilfe der folgenden Ansätze:

UseUrls
Befehlszeilenargument --urls
Hostkonfigurationsschlüssel urls
Umgebungsvariable ASPNETCORE_URLS

Diese Methoden sind nützlich, wenn Ihr Code mit anderen Servern als Kestrel funktionieren soll. Beachten Sie jedoch die folgenden Einschränkungen:

HTTPS kann nicht mit diesen Ansätzen verwendet werden, außer ein Standardzertifikat wird in der HTTPS-Endpunktkonfiguration angegeben (z. B. wenn Sie wie zuvor in diesem Artikel gezeigt die KestrelServerOptions-Konfiguration oder eine Konfigurationsdatei verwenden).
Wenn die Ansätze Listen und UseUrls gleichzeitig verwendet werden, überschreiben die Listen-Endpunkte die UseUrls-Endpunkte.

IIS-Endpunktkonfiguration

ListenOptions.Protocols

`HttpProtocols`-Enumerationswert	Zulässiges Verbindungsprotokoll
`Http1`	Nur HTTP/1.1. Kann mit oder ohne TLS verwendet werden.
`Http2`	Nur HTTP/2. Kann nur ohne TLS verwendet werden, wenn der Client einen Vorabkenntnis-Modus unterstützt.
`Http1AndHttp2`	HTTP/1.1 und HTTP/2. Für HTTP/2 muss der Client HTTP/2 im TLS ALPN-Handshake (Application-Layer Protocol Negotiation) auswählen, andernfalls wird standardmäßig eine HTTP/1.1 verwendet.

Der Standardwert von ListenOptions.Protocols ist für alle Endpunkte HttpProtocols.Http1AndHttp2.

TLS-Einschränkungen für HTTP/2:

TLS Version 1.2 oder höher
Erneute Aushandlung deaktiviert
Komprimierung deaktiviert
Minimale Größen für Austausch von flüchtigen Schlüsseln:
- ECDHE (Elliptic Curve Diffie-Hellman) [RFC4492]: mindestens 224 Bit
- DHE (Finite Field Diffie-Hellman) [TLS12]: mindestens 2048 Bit
Verschlüsselungssammlung nicht verboten

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] mit der elliptischen P-256-Kurve [FIPS186] wird standardmäßig unterstützt.

Das folgende Beispiel erlaubt HTTP/1.1- und HTTP/2-Verbindungen an Port 8000. Die Verbindungen werden durch TLS mit einem bereitgestellten Zertifikat geschützt:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

Unter Linux kann CipherSuitesPolicy zum Filtern von TLS-Handshakes auf Verbindungsbasis verwendet werden:

// using System.Net.Security;
// using Microsoft.AspNetCore.Hosting;
// using Microsoft.AspNetCore.Server.Kestrel.Core;
// using Microsoft.Extensions.DependencyInjection;
// using Microsoft.Extensions.Hosting;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.OnAuthenticate = (context, sslOptions) =>
        {
            sslOptions.CipherSuitesPolicy = new CipherSuitesPolicy(
                new[]
                {
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
                    TlsCipherSuite.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
                    // ...
                });
        };
    });
});

Verbindungsmiddleware

Benutzerdefinierte Verbindungsmiddleware kann bei Bedarf TLS-Handshakes auf Verbindungsbasis für bestimmte Verschlüsselungsverfahren filtern.

Es wird keine Verschlüsselung mit einem CipherAlgorithmType.Null-Verschlüsselungsalgorithmus verwendet.

// using System.Net;
// using Microsoft.AspNetCore.Connections;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.UseTlsFilter();
    });
});

using System;
using System.Security.Authentication;
using Microsoft.AspNetCore.Connections.Features;

namespace Microsoft.AspNetCore.Connections
{
    public static class TlsFilterConnectionMiddlewareExtensions
    {
        public static IConnectionBuilder UseTlsFilter(
            this IConnectionBuilder builder)
        {
            return builder.Use((connection, next) =>
            {
                var tlsFeature = connection.Features.Get<ITlsHandshakeFeature>();

                if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
                {
                    throw new NotSupportedException("Prohibited cipher: " +
                        tlsFeature.CipherAlgorithm);
                }

                return next();
            });
        }
    }
}

Die Verbindungsfilterung kann auch über einen IConnectionBuilder-Lambdaausdruck konfiguriert werden:

// using System;
// using System.Net;
// using System.Security.Authentication;
// using Microsoft.AspNetCore.Connections;
// using Microsoft.AspNetCore.Connections.Features;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Festlegen des HTTP-Protokolls in der Konfiguration

CreateDefaultBuilder ruft serverOptions.Configure(context.Configuration.GetSection("Kestrel")) standardmäßig zum Laden der Kestrel-Konfiguration auf.

Das folgende appsettings.json -Beispiel richtet HTTP/1.1 als Standardverbindungsprotokoll für alle Endpunkte ein:

{
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http1"
    }
  }
}

Das folgende appsettings.json -Beispiel richtet HTTP/1.1 als Verbindungsprotokoll für einen bestimmten Endpunkt ein:

{
  "Kestrel": {
    "Endpoints": {
      "HttpsDefaultCert": {
        "Url": "https://localhost:5001",
        "Protocols": "Http1"
      }
    }
  }
}

Protokolle, die in Code angegeben werden, setzen Werte außer Kraft, der durch die Konfiguration festgelegt werden.

URL-Präfixe

Nur HTTP-URL-Präfixe sind gültig. Kestrel unterstützt HTTPS nicht beim Konfigurieren von URL-Bindungen mit UseUrls.

IPv4-Adresse mit Portnummer
```
http://65.55.39.10:80/
```
Bei 0.0.0.0 handelt es sich um einen Sonderfall, für den eine Bindung an alle IPv4-Adressen erfolgt.
IPv6-Adresse mit Portnummer
```
http://[0:0:0:0:0:ffff:4137:270a]:80/
```
[::] stellt das Äquivalent von IPv6 zu 0.0.0.0 für IPv4 dar.
Hostname mit Portnummer
```
http://contoso.com:80/
http://*:80/
```
Hostnamen, * und + sind nicht spezifisch. Alle Elemente, die nicht als gültige IP-Adresse oder localhost erkannt werden, werden an alle IPv4- und IPv6-IP-Adressen gebunden. Verwenden Sie HTTP.sys oder einen Reverseproxyserver zum Binden verschiedener Hostnamen an verschiedene ASP.NET Core-Apps auf demselben Port. Beispiele für Reverseproxyserver sind IIS, Nginx oder Apache.

Warnung

Das Hosting in einer Reverseproxykonfiguration erfordert Hostfilterung.
localhost-Hostname mit Portnummer oder Loopback-IP mit Portnummer
```
http://localhost:5000/
http://127.0.0.1:5000/
http://[::1]:5000/
```
Wenn localhost angegeben ist, versucht Kestrel, eine Bindung zu IPv4- und IPv6-Loopback-Schnittstellen zu erstellen. Wenn der erforderliche Port von einem anderen Dienst auf einer der Loopback-Schnittstellen verwendet wird, tritt beim Starten von Kestrel ein Fehler auf. Wenn eine der Loopback-Schnittstellen aus anderen Gründen nicht verfügbar ist (meistens durch die fehlende Unterstützung von IPv6), protokolliert Kestrel eine Warnung.

Freigeben über

Konfigurieren von Endpunkten für den ASP.NET Core-Kestrel-Webserver

Standardendpunkt

Konfigurieren von Endpunkten

Konfigurieren von Endpunkten mit URLs

URL-Formate

HTTPS-URL-Präfixe

Reine Angabe von Ports

Konfigurieren von Endpunkten in „appsettings.json“

Erneutes Laden von Endpunkten aus der Konfiguration

ConfigurationLoader

Konfigurieren von Endpunkten im Code

Binden an einen TCP-Socket

Binden an einen Unix-Socket

Konfigurieren von Endpunktstandardeinstellungen

Dynamische Portbindung

Konfigurieren von HTTPS

Konfigurieren von HTTPS in „appsettings.json“

Schemahinweise

Zertifikatquellen

Konfigurieren von Clientzertifikaten in „appsettings.json“

Konfigurieren von SSL-/TLS-Protokollen in „appsettings.json“

Konfigurieren von HTTPS im Code

Konfigurieren von Clientzertifikaten im Code

Konfigurieren von HTTPS-Standardwerten im Code

Konfigurieren von SSL-/TLS-Protokollen im Code

Konfigurieren des Filters für TLS-Suites mit Verschlüsselungsverfahren im Code

Konfigurieren der Servernamensanzeige

Konfigurieren von SNI in „appsettings.json“

Konfigurieren von SNI mit Code

SNI mit ServerCertificateSelector

SNI mit ServerOptionsSelectionCallback

SNI mit TlsHandshakeCallbackOptions

Konfigurieren von HTTP-Protokollen

Konfigurieren von HTTP-Protokollen in „appsettings.json“

Konfigurieren von HTTP-Protokollen im Code

Weitere Informationen

ConfigureEndpointDefaults

Configure(IConfiguration)

ConfigureHttpsDefaults

ListenOptions.UseHttps

Keine Konfiguration

Ersetzen des Standardzertifikats aus der Konfiguration

Zertifikatquellen

ConfigurationLoader

Ändern des Standards im Code

Konfigurieren von Endpunkten mithilfe der Servernamensanzeige

SNI mit ServerCertificateSelector

SNI mit ServerOptionsSelectionCallback

SNI mit TlsHandshakeCallbackOptions

SNI in der Konfiguration

SNI-Anforderungen

SSL/TLS-Protokolle

Clientzertifikate

Verbindungsprotokollierung

Binden an einen TCP-Socket

Binden an einen Unix-Socket

Port 0

Einschränkungen

IIS-Endpunktkonfiguration

ListenOptions.Protocols

Verbindungsmiddleware

Festlegen des HTTP-Protokolls in der Konfiguration

URL-Präfixe

ConfigureEndpointDefaults

Configure(IConfiguration)

ConfigureHttpsDefaults

ListenOptions.UseHttps

Keine Konfiguration

Ersetzen des Standardzertifikats aus der Konfiguration

Zertifikatquellen

ConfigurationLoader

Ändern des Standards im Code

Konfigurieren von Endpunkten mithilfe der Servernamensanzeige

SNI mit ServerCertificateSelector

SNI mit ServerOptionsSelectionCallback

SNI mit TlsHandshakeCallbackOptions

SNI in der Konfiguration

SNI-Anforderungen

SSL/TLS-Protokolle

SNI mit `ServerCertificateSelector`

SNI mit `ServerOptionsSelectionCallback`

SNI mit `TlsHandshakeCallbackOptions`

SNI mit `ServerCertificateSelector`

SNI mit `ServerOptionsSelectionCallback`

SNI mit `TlsHandshakeCallbackOptions`

SNI mit `ServerCertificateSelector`

SNI mit `ServerOptionsSelectionCallback`

SNI mit `TlsHandshakeCallbackOptions`

SNI mit `ServerCertificateSelector`

SNI mit `ServerOptionsSelectionCallback`