Eindpunten configureren voor de webserver van ASP.NET Core Kestrel

Kestrel eindpunten bieden de infrastructuur voor het luisteren naar binnenkomende aanvragen en deze doorsturen naar de juiste middleware. De combinatie van een adres en een protocol definieert een eindpunt.

• Het adres geeft de netwerkinterface aan waarop de server luistert voor binnenkomende aanvragen, zoals een TCP-poort.
• Het protocol specificeert de communicatie tussen de client en de server, zoals HTTP/1.1, HTTP/2 of HTTP/3.
• Een eindpunt kan worden beveiligd met behulp van het https URL-schema of UseHttps methode.

Eindpunten kunnen worden geconfigureerd met behulp van URL's, JSON in appsettings.jsonen code. In dit artikel wordt beschreven hoe u elke optie gebruikt om een eindpunt te configureren:

• eindpunten configureren
• HTTPS- configureren
• HTTP-protocollen configureren

Standaardeindpunt

Nieuwe ASP.NET Core-projecten zijn geconfigureerd om verbinding te maken met een willekeurige HTTP-poort tussen 5000-5300 en een willekeurige HTTPS-poort tussen 7000-7300. De geselecteerde poorten worden opgeslagen in het gegenereerde Properties/launchSettings.json-bestand en kunnen worden gewijzigd door de ontwikkelaar. Het launchSetting.json-bestand wordt alleen gebruikt in lokale ontwikkeling.

Als er geen eindpuntconfiguratie is, wordt Kestrel verbonden met http://localhost:5000.

Eindpunten configureren

Kestrel eindpunten luisteren naar binnenkomende verbindingen. Wanneer een eindpunt wordt gemaakt, moet het worden geconfigureerd met het adres waarnaar het luistert. Dit is meestal een TCP-adres en poortnummer.

Er zijn verschillende opties voor het configureren van eindpunten:

• Eindpunten configureren met URL's
• Alleen poorten opgeven
• Eindpunten configureren in appsettings.json
• Eindpunten configureren in code

Eindpunten configureren met URL's

In de volgende secties wordt uitgelegd hoe u eindpunten configureert met behulp van:

• ASPNETCORE_URLS omgevingsvariabele.
• --urls opdrachtregelargument.
• urls hostconfiguratiesleutel.
• UseUrls extensiemethode.
• WebApplication.Urls eigenschap.

URL-indelingen

De URL's geven het IP- of hostadres aan met poorten en protocollen waarop de server moet luisteren. De poort kan worden weggelaten als dit de standaardwaarde is voor het protocol (meestal 80 en 443). URL's kunnen een van de volgende indelingen hebben.

• IPv4-adres met poortnummer

  http://65.55.39.10:80/
  

  0.0.0.0 is een speciaal geval dat is gekoppeld aan alle IPv4-adressen.

• IPv6-adres met poortnummer

  http://[0:0:0:0:0:ffff:4137:270a]:80/
  

  [::] is het IPv6-equivalent van IPv4-0.0.0.0.

• Wildcard-host met poortnummer

  http://contoso.com:80/
  http://*:80/
  

  Alles wat niet wordt herkend als een geldig IP-adres of localhost wordt behandeld als een jokerteken dat is gekoppeld aan alle IPv4- en IPv6-adressen. Sommige mensen willen * of + gebruiken om explicieter te zijn. Als u verschillende hostnamen wilt binden aan verschillende ASP.NET Core-apps op dezelfde poort, gebruikt u HTTP.sys of een omgekeerde proxyserver.

  Voorbeelden van omgekeerde proxyservers zijn IIS, YARP, Nginx en Apache.

• Hostnaam localhost met poortnummer of loopback-IP-adres met poortnummer

  http://localhost:5000/
  http://127.0.0.1:5000/
  http://[::1]:5000/
  

  Wanneer localhost is opgegeven, probeert Kestrel verbinding te maken met zowel IPv4- als IPv6-loopback-interfaces. Als de aangevraagde poort wordt gebruikt door een andere service in een loopback-interface, kan Kestrel niet worden gestart. Als een loopback-interface om een andere reden niet beschikbaar is (meestal omdat IPv6 niet wordt ondersteund), Kestrel een waarschuwing registreert.

Meerdere URL-voorvoegsels kunnen worden opgegeven met behulp van een puntkomma (;) scheidingsteken:

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

Zie override-configuratievoor meer informatie.

HTTPS-URL-voorvoegsels

HTTPS-URL-voorvoegsels kunnen alleen worden gebruikt om eindpunten te definiëren als er een standaardcertificaat is opgegeven in de configuratie van het HTTPS-eindpunt. Gebruik bijvoorbeeld KestrelServerOptions configuratie of een configuratiebestand, zoals wordt weergegeven verderop in dit artikel.

Zie HTTPS-configureren voor meer informatie.

Alleen poorten opgeven

Apps en containers krijgen vaak alleen een poort om op te luisteren, zoals poort 80, zonder extra beperkingen, zoals host of pad. HTTP_PORTS en HTTPS_PORTS zijn configuratiesleutels waarmee de luisterpoorten voor de Kestrel- en HTTP.sys-servers worden opgegeven. Deze sleutels kunnen worden opgegeven als omgevingsvariabelen die zijn gedefinieerd met de DOTNET_ of ASPNETCORE_ voorvoegsels, of rechtstreeks worden opgegeven via andere configuratie-invoer, zoals appsettings.json. Elk is een door puntkomma's gescheiden lijst met poortwaarden, zoals wordt weergegeven in het volgende voorbeeld:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Het voorgaande voorbeeld is een afkorting voor de volgende configuratie, waarmee het schema (HTTP of HTTPS) en een host of IP wordt opgegeven.

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

De HTTP_PORTS en HTTPS_PORTS configuratiesleutels hebben een lagere prioriteit en worden overschreven door URL's of waarden die rechtstreeks in code worden geleverd. Certificaten moeten nog steeds afzonderlijk worden geconfigureerd via serverspecifieke mechanica voor HTTPS.

Eindpunten configureren in appsettings.json

Kestrel kan eindpunten laden vanuit een IConfiguration exemplaar. Standaard wordt Kestrel configuratie geladen vanuit de sectie Kestrel en worden eindpunten geconfigureerd in Kestrel:Endpoints:

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

Het voorgaande voorbeeld:

• Gebruikt appsettings.json als de configuratiebron. Elke IConfiguration bron kan echter worden gebruikt.
• Hiermee voegt u een eindpunt toe met de naam MyHttpEndpoint op poort 8080.

Zie latere secties in dit artikel voor meer informatie over het configureren van eindpunten met JSON het configureren van HTTPS- en het configureren van HTTP-protocollen in appsettings.json.

Eindpunten opnieuw laden vanuit de configuratie

Eindpuntconfiguratie opnieuw laden wanneer de configuratiebronwijzigingen standaard zijn ingeschakeld. Het kan worden uitgeschakeld met behulp van KestrelServerOptions.Configure(IConfiguration, Boolean).

Als een wijziging wordt gesignaleerd, worden de volgende stappen uitgevoerd:

• De nieuwe configuratie wordt vergeleken met het oude en elk eindpunt zonder configuratiewijzigingen wordt niet gewijzigd.
• Verwijderde of gewijzigde eindpunten krijgen vijf seconden om de verwerking van aanvragen te voltooien en af te sluiten.
• Nieuwe of gewijzigde eindpunten worden gestart.

Clients die verbinding maken met een gewijzigd eindpunt, kunnen worden verbroken of geweigerd terwijl het eindpunt opnieuw wordt opgestart.

ConfigurationLoader

KestrelServerOptions.Configure geeft een KestrelConfigurationLoaderterug. De Endpoint(String, Action<EndpointConfiguration>) methode van het laadprogramma dat kan worden gebruikt om de instellingen van een geconfigureerd eindpunt aan te vullen:

var builder = WebApplication.CreateBuilder(args);

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

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

KestrelServerOptions.ConfigurationLoader kan rechtstreeks worden geopend om door te gaan met het bestaande laadprogramma, zoals het laadprogramma dat door WebApplicationBuilder.WebHostwordt geleverd.

• De configuratiesectie voor elk eindpunt is beschikbaar op de opties in de methode Endpoint, zodat aangepaste instellingen kunnen worden gelezen.
• KestrelServerOptions.Configure(IConfiguration) kan meerdere keren worden aangeroepen, maar alleen de laatste configuratie wordt gebruikt, tenzij Load expliciet wordt aangeroepen op eerdere exemplaren. De standaardhost roept geen Load aan, zodat de standaardconfiguratiesectie kan worden vervangen.
• KestrelConfigurationLoader weerspiegelt de Listen API-familie van KestrelServerOptions als Endpoint overloads, zodat code- en configuratie-eindpunten op dezelfde plaats kunnen worden geconfigureerd. Deze overbelastingen gebruiken geen namen en verbruiken alleen standaardinstellingen uit de configuratie.

Eindpunten configureren in code

KestrelServerOptions biedt methoden voor het configureren van eindpunten in code:

• Listen
• ListenLocalhost
• ListenAnyIP
• ListenUnixSocket
• ListenNamedPipe

Wanneer zowel de Listen als UseUrls API's tegelijkertijd worden gebruikt, overschrijven de Listen eindpunten de UseUrls-eindpunten.

Verbinding maken met een TCP-socket

De methoden Listen, ListenLocalhosten ListenAnyIP verbinden zich met een TCP-socket:

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

Het voorgaande voorbeeld:

• Hiermee configureert u eindpunten die luisteren op poort 5000 en 5001.
• Hiermee configureert u HTTPS voor een eindpunt met de UseHttps-extensiemethode op ListenOptions. Zie HTTPS configureren in codevoor meer informatie.

In Windows kunnen zelfondertekende certificaten worden gemaakt met behulp van de New-SelfSignedCertificate PowerShell-cmdlet. Zie UpdateIISExpressSSLForChrome.ps1voor een niet-ondersteund voorbeeld.

In macOS, Linux en Windows kunnen certificaten worden gemaakt met behulp van OpenSSL-.

Binden aan een Unix-socket

Luister op een Unix-socket met ListenUnixSocket voor verbeterde prestaties met Nginx, zoals wordt weergegeven in dit voorbeeld:

var builder = WebApplication.CreateBuilder(args);

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

• Stel in het Nginx-configuratiebestand de server>location>proxy_pass vermelding in op http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} is de naam van de socket die is opgegeven voor ListenUnixSocket (bijvoorbeeld kestrel-test.sock in het vorige voorbeeld).
• Zorg ervoor dat de socket kan worden geschreven door Nginx (bijvoorbeeld chmod go+w /tmp/kestrel-test.sock).

Standaardinstellingen voor eindpunten configureren

ConfigureEndpointDefaults(Action<ListenOptions>) geeft configuratie op die wordt uitgevoerd voor elk opgegeven eindpunt. Het aanroepen van ConfigureEndpointDefaults meerdere keren vervangt de vorige configuratie.

var builder = WebApplication.CreateBuilder(args);

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

Notitie

Eindpunten die zijn gemaakt door Listenaan te roepen voordatConfigureEndpointDefaults worden aangeroepen, worden de standaardwaarden niet toegepast.

Dynamische poortbinding

Wanneer poortnummer 0 is opgegeven, wordt Kestrel dynamisch verbonden met een beschikbare poort. In het volgende voorbeeld wordt getoond hoe u kunt bepalen aan welke poort Kestrel is gebonden tijdens runtime.

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

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

        // ...
    }
});

Dynamisch verbinden van een poort is in sommige situaties niet beschikbaar:

• KestrelServerOptions.ListenLocalhost
• Het samenbinden van TCP-gebaseerde HTTP/1.1 of HTTP/2 en QUIC-gebaseerde HTTP/3.

HTTPS configureren

Kestrel ondersteunt het beveiligen van eindpunten met HTTPS. Gegevens die via HTTPS worden verzonden, worden versleuteld met behulp van TLS- (Transport Layer Security) om de beveiliging van gegevens die worden overgedragen tussen de client en de server te verhogen.

HTTPS vereist een TLS-certificaat. Het TLS-certificaat wordt opgeslagen op de server en Kestrel is geconfigureerd om het te gebruiken. Een app kan het ASP.NET Core HTTPS-ontwikkelingscertificaat in een lokale ontwikkelomgeving gebruiken. Het ontwikkelingscertificaat is niet geïnstalleerd in niet-ontwikkelingsomgevingen. In productie moet een TLS-certificaat expliciet worden geconfigureerd. Er moet ten minste één standaard certificaat worden opgegeven.

De manier waarop HTTPS en het TLS-certificaat worden geconfigureerd, is afhankelijk van hoe eindpunten worden geconfigureerd:

• Als URL-voorvoegsels of alleen poorten opgeeft worden gebruikt om eindpunten te definiëren, kan HTTPS alleen worden gebruikt als er een standaardcertificaat is opgegeven in de configuratie van het HTTPS-eindpunt. Een standaardcertificaat kan worden geconfigureerd met een van de volgende opties:
• HTTPS configureren in appsettings.json
• HTTPS configureren in code

HTTPS configureren in appsettings.json

Er is een standaardconfiguratieschema voor HTTPS-app-instellingen beschikbaar voor Kestrel. Configureer meerdere eindpunten, inclusief de URL's en de certificaten die moeten worden gebruikt, vanuit een bestand op schijf of vanuit een certificaatarchief.

Elk HTTPS-eindpunt dat geen certificaat opgeeft (HttpsDefaultCert in het volgende voorbeeld) valt terug op het certificaat dat is gedefinieerd onder Certificates:Default of het ontwikkelingscertificaat.

Het volgende voorbeeld is voor appsettings.json, maar elke configuratiebron kan worden gebruikt:

{
  "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$"
      }
    }
  }
}

Waarschuwing

In het voorgaande voorbeeld wordt het certificaatwachtwoord opgeslagen in tekst zonder opmaak in appsettings.json. Het $CREDENTIAL_PLACEHOLDER$ token wordt gebruikt als tijdelijke aanduiding voor het wachtwoord van het certificaat. Als u certificaatwachtwoorden veilig wilt opslaan in ontwikkelomgevingen, raadpleegt u Geheimen beveiligen in de ontwikkelomgeving. Zie Azure Key Vault-configuratieproviderom certificaatwachtwoorden veilig op te slaan in productieomgevingen. Ontwikkelingsgeheimen mogen niet worden gebruikt voor productie of test.

Schemanotities

• Eindpuntnamen zijn niet hoofdlettergevoelig. HTTPS en Https zijn bijvoorbeeld gelijkwaardig.
• De parameter Url is vereist voor elk eindpunt. De indeling voor deze parameter is hetzelfde als de configuratieparameter op het hoogste niveau Urls, behalve dat deze is beperkt tot één waarde. Zie URL-indelingen eerder in dit artikel.
• Deze eindpunten vervangen de eindpunten die zijn gedefinieerd in de configuratie op het hoogste niveau Urls in plaats van ze toe te voegen. Eindpunten die zijn gedefinieerd in code via Listen zijn cumulatief met de eindpunten die zijn gedefinieerd in de configuratiesectie.
• De sectie Certificate is optioneel. Als de Certificate sectie niet is opgegeven, worden de standaardwaarden gebruikt die zijn gedefinieerd in Certificates:Default. Als er geen standaardinstellingen beschikbaar zijn, wordt het ontwikkelingscertificaat gebruikt. Als er geen standaardwaarden zijn en het ontwikkelingscertificaat niet aanwezig is, genereert de server een uitzondering en kan deze niet worden gestart.
• De sectie Certificate ondersteunt meerdere certificaatbronnen.
• Een willekeurig aantal eindpunten kan worden gedefinieerd in Configuration, zolang ze geen poortconflicten veroorzaken.

Certificaatbronnen

Certificaatknooppunten kunnen worden geconfigureerd voor het laden van certificaten uit een aantal bronnen:

• Path en Password om .pfx-bestanden te laden.
• Path, KeyPath en Password om .pem-/.crt-- en .key-bestanden te laden.
• Subject en Store gebruiken om vanuit het certificaatopslag te laden.

Het Certificates:Default certificaat kan bijvoorbeeld worden opgegeven als:

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

Clientcertificaten configureren in appsettings.json

ClientCertificateMode wordt gebruikt om gedrag van clientcertificaten te configureren.

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

Waarschuwing

In het voorgaande voorbeeld wordt het certificaatwachtwoord opgeslagen in tekst zonder opmaak in appsettings.json. Het $CREDENTIAL_PLACEHOLDER$ token wordt gebruikt als tijdelijke aanduiding voor het wachtwoord van het certificaat. Als u certificaatwachtwoorden veilig wilt opslaan in ontwikkelomgevingen, raadpleegt u Geheimen beveiligen in de ontwikkelomgeving. Zie Azure Key Vault-configuratieproviderom certificaatwachtwoorden veilig op te slaan in productieomgevingen. Ontwikkelingsgeheimen mogen niet worden gebruikt voor productie of test.

De standaardwaarde is ClientCertificateMode.NoCertificate, waarbij Kestrel geen certificaat van de client aanvraagt of vereist.

Zie Certificaatverificatie configureren in ASP.NET Corevoor meer informatie.

SSL/TLS-protocollen configureren in appsettings.json

SSL-protocollen zijn protocollen die worden gebruikt voor het versleutelen en ontsleutelen van verkeer tussen twee peers, traditioneel een client en een server.

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

Waarschuwing

In het voorgaande voorbeeld wordt het certificaatwachtwoord opgeslagen in tekst zonder opmaak in appsettings.json. Het $CREDENTIAL_PLACEHOLDER$ token wordt gebruikt als tijdelijke aanduiding voor het wachtwoord van het certificaat. Als u certificaatwachtwoorden veilig wilt opslaan in ontwikkelomgevingen, raadpleegt u Geheimen beveiligen in de ontwikkelomgeving. Zie Azure Key Vault-configuratieproviderom certificaatwachtwoorden veilig op te slaan in productieomgevingen. Ontwikkelingsgeheimen mogen niet worden gebruikt voor productie of test.

De standaardwaarde, SslProtocols.None, zorgt ervoor dat Kestrel de standaardinstellingen van het besturingssysteem gebruikt om het beste protocol te kiezen. Gebruik de standaardwaarde, tenzij u een specifieke reden hebt om een protocol te selecteren.

HTTPS configureren in code

Wanneer u de Listen-API gebruikt, is de UseHttps-extensiemethode op ListenOptions beschikbaar om HTTPS te configureren.

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 parameters:

• filename is het pad en de bestandsnaam van een certificaatbestand, ten opzichte van de map die de inhoudsbestanden van de app bevat.
• password is het wachtwoord dat is vereist voor toegang tot de X.509-certificaatgegevens.
• configureOptions is een Action om de HttpsConnectionAdapterOptionste configureren. Retourneert de ListenOptions.
• storeName is het certificaatarchief waaruit het certificaat moet worden geladen.
• subject is de onderwerpnaam voor het certificaat.
• allowInvalid geeft aan of er ongeldige certificaten moeten worden overwogen, zoals zelfondertekende certificaten.
• location is de opslaglocatie waaruit het certificaat moet worden geladen.
• serverCertificate is het X.509-certificaat.

Zie UseHttpsvoor een volledige lijst met UseHttps overbelastingen.

Clientcertificaten configureren in code

ClientCertificateMode configureert de vereisten voor het clientcertificaat.

var builder = WebApplication.CreateBuilder(args);

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

De standaardwaarde is NoCertificate, waarbij Kestrel geen certificaat van de client aanvraagt of vereist.

Zie Certificaatverificatie configureren in ASP.NET Corevoor meer informatie.

HTTPS-standaardinstellingen configureren in code

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) een configuratie Action voor elk HTTPS-eindpunt moet worden uitgevoerd. Als u ConfigureHttpsDefaults meerdere keren aanroept, worden eerdere Action exemplaren vervangen door de laatst opgegeven Action.

var builder = WebApplication.CreateBuilder(args);

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

Notitie

Eindpunten die zijn gemaakt door Listenaan te roepen voordatConfigureHttpsDefaults worden aangeroepen, worden de standaardwaarden niet toegepast.

SSL/TLS-protocollen configureren in code

SSL-protocollen zijn protocollen die worden gebruikt voor het versleutelen en ontsleutelen van verkeer tussen twee peers, traditioneel een client en een server.

var builder = WebApplication.CreateBuilder(args);

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

Filter voor TLS-coderingssuites configureren in code

In Linux kan CipherSuitesPolicy worden gebruikt om TLS-handshakes per verbinding te filteren:

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,
                    // ...
                });
        };
    });
});

Servernaamindicatie configureren

SNI- (Server Name Indication) kan worden gebruikt om meerdere domeinen op hetzelfde IP-adres en dezelfde poort te hosten. SNI kan worden gebruikt om resources te besparen door meerdere sites van één server te bedienen.

Om SNI te laten functioneren, verzendt de client de hostnaam voor de beveiligde sessie naar de server tijdens de TLS-handshake, zodat de server het juiste certificaat kan opgeven. De client gebruikt het ingerichte certificaat voor versleutelde communicatie met de server tijdens de beveiligde sessie die de TLS-handshake volgt.

Alle websites moeten worden uitgevoerd op hetzelfde Kestrel exemplaar. Kestrel biedt geen ondersteuning voor het delen van een IP-adres en poort tussen meerdere exemplaren zonder omgekeerde proxy.

SNI kan op twee manieren worden geconfigureerd:

• Configureer een toewijzing tussen hostnamen en HTTPS-opties in Configuration. Bijvoorbeeld JSON in het bestand appsettings.json.
• Maak een eindpunt in code en selecteer een certificaat met behulp van de hostnaam met de ServerCertificateSelector callback.

SNI configureren in appsettings.json

Kestrel ondersteunt SNI die is gedefinieerd in de configuratie. Een eindpunt kan worden geconfigureerd met een Sni-object dat een toewijzing tussen hostnamen en HTTPS-opties bevat. De hostnaam van de verbinding wordt vergeleken met de opties en deze worden gebruikt voor die verbinding.

Met de volgende configuratie wordt een eindpunt met de naam MySniEndpoint toegevoegd dat SNI gebruikt om HTTPS-opties te selecteren op basis van de hostnaam:

{
  "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$"
      }
    }
  }
}

Waarschuwing

In het voorgaande voorbeeld wordt het certificaatwachtwoord opgeslagen in tekst zonder opmaak in appsettings.json. Het $CREDENTIAL_PLACEHOLDER$ token wordt gebruikt als tijdelijke aanduiding voor het wachtwoord van het certificaat. Als u certificaatwachtwoorden veilig wilt opslaan in ontwikkelomgevingen, raadpleegt u Geheimen beveiligen in de ontwikkelomgeving. Zie Azure Key Vault-configuratieproviderom certificaatwachtwoorden veilig op te slaan in productieomgevingen. Ontwikkelingsgeheimen mogen niet worden gebruikt voor productie of test.

HTTPS-opties die kunnen worden overschreven door SNI:

• Certificate configureert de certificaatbron.
• Protocols configureert de toegestane HTTP-protocollen.
• SslProtocols configureert de toegestane SSL-protocollen.
• ClientCertificateMode configureert de vereisten voor clientcertificaten.

De hostnaam ondersteunt jokertekenkoppeling:

• Exacte overeenkomst. a.example.org komt bijvoorbeeld overeen met a.example.org.
• Jokertekenvoorvoegsel. Als er meerdere wildcard-overeenkomsten zijn, wordt het langste patroon gekozen. *.example.org komt bijvoorbeeld overeen met b.example.org en c.example.org.
• Volledige wildcard. * komt overeen met alle andere, inclusief clients die geen SNI gebruiken en geen hostnaam verzenden.

De overeenkomende SNI-configuratie wordt toegepast op het eindpunt voor de verbinding, waarbij waarden op het eindpunt worden overschreven. Als een verbinding niet overeenkomt met een geconfigureerde SNI-hostnaam, wordt de verbinding geweigerd.

SNI configureren met code

Kestrel ondersteunt SNI met verschillende callback-API's:

• ServerCertificateSelector
• ServerOptionsSelectionCallback
• TlsHandshakeCallbackOptions

SNI met ServerCertificateSelector

Kestrel ondersteunt SNI via de ServerCertificateSelector callback. De callback wordt eenmaal per verbinding aangeroepen, zodat de app de hostnaam kan controleren en het juiste certificaat selecteert:

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 met ServerOptionsSelectionCallback

Kestrel ondersteunt aanvullende dynamische TLS-configuratie via de ServerOptionsSelectionCallback callback. De callback wordt eenmaal per verbinding aangeroepen, zodat de app de hostnaam kan inspecteren en het juiste certificaat en de TLS-configuratie selecteert. Standaardcertificaten en ConfigureHttpsDefaults worden niet gebruikt met deze callback.

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 met TlsHandshakeCallbackOptions

Kestrel ondersteunt aanvullende dynamische TLS-configuratie via de TlsHandshakeCallbackOptions.OnConnection callback. De callback wordt eenmaal per verbinding aangeroepen, zodat de app de hostnaam kan inspecteren en het juiste certificaat, de TLS-configuratie en andere serveropties selecteert. Standaardcertificaten en ConfigureHttpsDefaults worden niet gebruikt met deze callback.

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

HTTP-protocollen configureren

Kestrel ondersteunt alle veelgebruikte HTTP-versies. Eindpunten kunnen worden geconfigureerd ter ondersteuning van verschillende HTTP-versies met behulp van de HttpProtocols enum, waarmee beschikbare HTTP-versieopties worden opgegeven.

TLS is vereist om meer dan één HTTP-versie te ondersteunen. De ALPN -handshake (TLSApplication-Layer Protocol Negotiate) wordt gebruikt om te onderhandelen over het verbindingsprotocol tussen de client en de server wanneer een eindpunt meerdere protocollen ondersteunt.

HttpProtocols Waarde	Verbindingsprotocol toegestaan
Http1	Alleen HTTP/1.1. Kan worden gebruikt met of zonder TLS.
Http2	Alleen HTTP/2. Kan alleen zonder TLS worden gebruikt als de client ondersteuning biedt voor een Prior Knowledge Mode.
Http3	Alleen HTTP/3. Vereist TLS. De client moet mogelijk alleen worden geconfigureerd voor het gebruik van HTTP/3.
Http1AndHttp2	HTTP/1.1 en HTTP/2. HTTP/2 vereist dat de client HTTP/2 selecteert in de TLS Application-Layer Protocol Negotiation (ALPN) handshake; anders wordt de verbinding standaard ingesteld op HTTP/1.1.
Http1AndHttp2AndHttp3	HTTP/1.1, HTTP/2 en HTTP/3. De eerste clientaanvraag maakt normaal gesproken gebruik van HTTP/1.1 of HTTP/2 en de alt-svc antwoordheader vraagt de client om een upgrade naar HTTP/3 uit te voeren. VOOR HTTP/2 en HTTP/3 is TLS vereist; anders wordt de verbinding standaard ingesteld op HTTP/1.1.

De standaardprotocolwaarde voor een eindpunt is HttpProtocols.Http1AndHttp2.

TLS-beperkingen voor HTTP/2:

• TLS-versie 1.2 of hoger
• Heronderhandeling uitgeschakeld
• Compressie uitgeschakeld
• Minimale kortstondige sleuteluitwisselingsgrootten:
  • Elliptische curve Diffie-Hellman (ECDHE) [RFC4492]: minimaal 224 bits
  • Eindig veld Diffie-Hellman (DHE) [TLS12]: minimaal 2048 bits
• De coderingssuite is niet verboden.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] met de P-256 elliptische curve [FIPS186] wordt standaard ondersteund.

HTTP-protocollen configureren in appsettings.json

In het volgende appsettings.json voorbeeld wordt het HTTP/1.1-verbindingsprotocol voor een specifiek eindpunt vastgesteld:

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

Een standaardprotocol kan worden geconfigureerd in de sectie Kestrel:EndpointDefaults. In het volgende appsettings.json voorbeeld wordt HTTP/1.1 tot stand gebracht als het standaardverbindingsprotocol voor alle eindpunten:

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

Protocollen die zijn opgegeven in code overschrijven waarden die zijn ingesteld door de configuratie.

HTTP-protocollen in code configureren

ListenOptions.Protocols wordt gebruikt om protocollen op te geven met de HttpProtocols enum.

In het volgende voorbeeld wordt een eindpunt geconfigureerd voor HTTP/1.1-, HTTP/2- en HTTP/3-verbindingen op poort 8000. Verbindingen worden beveiligd door TLS met een opgegeven certificaat:

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

Zie ook

• Kestrel webserver in ASP.NET Core
• Opties configureren voor de ASP.NET Core Kestrel webserver