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

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:

• Listen
• ListenLocalhost
• ListenAnyIP
• ListenUnixSocket
• ListenNamedPipe

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

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.

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

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.

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

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.

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

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:

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

• Kestrel-Webserver in ASP.NET Core
• Konfigurieren von Optionen für den Kestrel-Webserver in ASP.NET Core