Konfigurera slutpunkter för webbservern ASP.NET Core Kestrel

Kestrel slutpunkter tillhandahåller infrastrukturen för att lyssna på inkommande begäranden och dirigera dem till rätt mellanprogram. Kombinationen av en adress och ett protokoll definierar en slutpunkt.

• Adressen anger det nätverksgränssnitt som servern lyssnar på för inkommande begäranden, till exempel en TCP-port.
• Protokollet anger kommunikationen mellan klienten och servern, till exempel HTTP/1.1, HTTP/2 eller HTTP/3.
• En slutpunkt kan skyddas med hjälp av https URL-schema eller UseHttps metod.

Slutpunkter kan konfigureras med hjälp av URL:er, JSON i appsettings.jsonoch kod. I den här artikeln beskrivs hur du använder varje alternativ för att konfigurera en slutpunkt:

• Konfigurera slutpunkter
• Konfigurera HTTPS-
• Konfigurera HTTP-protokoll

Standardslutpunkt

Nya ASP.NET Core-projekt har konfigurerats för att binda till en slumpmässig HTTP-port mellan 5000-5300 och en slumpmässig HTTPS-port mellan 7000 och 7300. De valda portarna lagras i den genererade Properties/launchSettings.json-filen och kan ändras av utvecklaren. Filen launchSetting.json används endast i lokal utveckling.

Om det inte finns någon slutpunktskonfiguration, då binds Kestrel till http://localhost:5000.

Konfigurera slutpunkter

Kestrel noder lyssnar efter inkommande anslutningar. När en slutpunkt skapas måste den konfigureras med den adress som den lyssnar på. Det här är vanligtvis en TCP-adress och ett portnummer.

Det finns flera alternativ för att konfigurera slutpunkter:

• Konfigurera slutpunkter med URL:er
• Ange endast portar
• Konfigurera slutpunkter i appsettings.json
• Konfigurera slutpunkter i kod

Konfigurera slutpunkter med URL:er

I följande avsnitt beskrivs hur du konfigurerar slutpunkter med hjälp av:

• ASPNETCORE_URLS miljövariabel.
• --urls kommandoradsargument.
• urls värdkonfigurationsnyckel.
• UseUrls utvidgningsmetod.
• WebApplication.Urls-egenskapen.

URL-format

URL:erna anger IP- eller värdadresserna med portar och protokoll som servern ska lyssna på. Porten kan utelämnas om det är standardvärdet för protokollet (vanligtvis 80 och 443). URL:er kan finnas i något av följande format.

• IPv4-adress med portnummer

  http://65.55.39.10:80/
  

  0.0.0.0 är ett specialfall som binder till alla IPv4-adresser.

• IPv6-adress med portnummer

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

  [::] är IPv6-motsvarigheten till IPv4 0.0.0.0.

• Wildcard-värd med portnummer

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

  Allt som inte känns igen som en giltig IP-adress eller localhost behandlas som ett jokertecken som binder till alla IPv4- och IPv6-adresser. Vissa personer gillar att använda * eller + för att vara mer explicita. Om du vill binda olika värdnamn till olika ASP.NET Core-appar på samma port använder du HTTP.sys eller en omvänd proxyserver.

  Exempel på omvänd proxyserver är IIS, YARP, Nginx och Apache.

• Värdnamn localhost med portnummer eller loopback-IP med portnummer

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

  När localhost anges försöker Kestrel binda till både IPv4- och IPv6-loopback-gränssnitt. Om den begärda porten används av en annan tjänst i något av loopback-gränssnitten kan Kestrel inte starta. Om något av loopback-gränssnittet inte är tillgängligt av någon annan anledning (oftast eftersom IPv6 inte stöds) loggar Kestrel en varning.

Flera URL-prefix kan anges med hjälp av en semikolon (;) avgränsare:

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

För mer information, se åsidosättningskonfiguration.

HTTPS-URL-prefixet

HTTPS-URL-prefix kan endast användas för att definiera slutpunkter om ett standardcertifikat anges i HTTPS-slutpunktskonfigurationen. Använd till exempel KestrelServerOptions konfiguration eller en konfigurationsfil, vilket visas senare i den här artikeln.

Mer information finns i Konfigurera HTTPS-.

Ange endast portar

Appar och containrar får ofta bara en port att lyssna på, till exempel port 80, utan ytterligare begränsningar som värd eller sökväg. HTTP_PORTS och HTTPS_PORTS är konfigurationsnycklar som anger lyssnarportarna för servrarna Kestrel och HTTP.sys. Dessa nycklar kan anges som miljövariabler som definieras med prefixen DOTNET_ eller ASPNETCORE_ eller anges direkt via andra konfigurationsindata, till exempel appsettings.json. Var och en är en semikolonavgränsad lista med portvärden, som du ser i följande exempel:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Föregående exempel är en förkortning för följande konfiguration, som anger schemat (HTTP eller HTTPS) och valfri värd eller IP-adress.

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

Konfigurationsnycklarna HTTP_PORTS och HTTPS_PORTS har lägre prioritet och åsidosättas av URL:er eller värden som anges direkt i koden. Certifikat måste fortfarande konfigureras separat via serverspecifik mekanik för HTTPS.

Konfigurera slutpunkter i appsettings.json

Kestrel kan läsa in slutpunkter från en IConfiguration instans. Som standardinställning läses konfigurationen för Kestrel från Kestrel-avsnittet och slutpunkter konfigureras i Kestrel:Endpoints:

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

Föregående exempel:

• Använder appsettings.json som konfigurationskälla. Vilken som helst IConfiguration-källa kan dock användas.
• Lägger till en slutpunkt med namnet MyHttpEndpoint på port 8080.

Mer information om hur du konfigurerar slutpunkter med JSON finns i senare avsnitt i den här artikeln om konfiguration av HTTPS- och konfiguration av HTTP-protokoll i appsettings.json.

Läsa in slutpunkter från konfigurationen igen

Omladdning av slutpunktskonfigurationen när konfigurationskällan ändras är aktiverat som standard. Den kan inaktiveras med hjälp av KestrelServerOptions.Configure(IConfiguration, Boolean).

Om en ändring signaleras vidtas följande steg:

• Den nya konfigurationen jämförs med den gamla och alla slutpunkter utan konfigurationsändringar ändras inte.
• Borttagna eller ändrade slutpunkter ges 5 sekunder för att slutföra bearbetningsbegäranden och stängas av.
• Nya eller ändrade slutpunkter startas.

Klienter som ansluter till en ändrad slutpunkt kan kopplas från eller nekas medan slutpunkten startas om.

Konfigurationsladdare

KestrelServerOptions.Configure returnerar en KestrelConfigurationLoader. Inläsarens Endpoint(String, Action<EndpointConfiguration>) metod som kan användas för att komplettera inställningarna för en konfigurerad slutpunkt:

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 nås direkt för att fortsätta med iterationerna av den befintliga laddaren, till exempel den som tillhandahålls av WebApplicationBuilder.WebHost.

• Konfigurationsavsnittet för varje slutpunkt finns på alternativen i metoden Endpoint så att anpassade inställningar kan läsas.
• KestrelServerOptions.Configure(IConfiguration) kan anropas flera gånger, men endast den senaste konfigurationen används om inte Load uttryckligen anropas på tidigare instanser. Standardvärden anropar inte Load så att standardkonfigurationsavsnittet kan ersättas.
• KestrelConfigurationLoader speglar Listen-serien med API:er från KestrelServerOptions som Endpoint överlagringar, så att kod- och konfigurationsslutpunkter kan konfigureras på samma plats. Dessa överlagringar använder inte namn och använder bara standardinställningar från konfigurationen.

Konfigurera slutpunkter i kod

KestrelServerOptions innehåller metoder för att konfigurera slutpunkter i kod:

• Listen
• ListenLocalhost
• ListenAnyIP
• ListenUnixSocket
• ListenNamedPipe

När både Listen och UseUrls API:er används samtidigt åsidosätter Listen slutpunkter UseUrls slutpunkter.

Binda till en TCP-socket

Metoderna Listen, ListenLocalhostoch ListenAnyIP binder till en 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");
    });
});

Föregående exempel:

• Konfigurerar slutpunkter som lyssnar på port 5000 och 5001.
• Konfigurerar HTTPS för en slutpunkt med UseHttps-tilläggsmetoden på ListenOptions. Mer information finns i Konfigurera HTTPS i kod.

I Windows kan självsignerade certifikat skapas med hjälp av New-SelfSignedCertificate PowerShell-cmdleten. För ett exempel som inte stöds, se UpdateIISExpressSSLForChrome.ps1.

På macOS, Linux och Windows kan certifikat skapas med OpenSSL-.

Binda till en Unix-socket

Lyssna på en Unix-socket med ListenUnixSocket för bättre prestanda med Nginx, som du ser i det här exemplet:

var builder = WebApplication.CreateBuilder(args);

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

• I Nginx-konfigurationsfilen ställ in posten server>location>proxy_pass till http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} är namnet på socketen som anges för ListenUnixSocket (till exempel kestrel-test.sock i föregående exempel).
• Kontrollera att socketen kan skrivas av Nginx (till exempel chmod go+w /tmp/kestrel-test.sock).

Konfigurera standardvärden för slutpunkter

ConfigureEndpointDefaults(Action<ListenOptions>) anger konfiguration som körs för varje angiven slutpunkt. Om du anropar ConfigureEndpointDefaults flera gånger ersätts den tidigare konfigurationen.

var builder = WebApplication.CreateBuilder(args);

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

Not

Slutpunkter som skapas genom att anropa Listeninnan anropar ConfigureEndpointDefaults har inte standardvärdena tillämpade.

Dynamisk portbindning

När portnummer 0 anges binder Kestrel dynamiskt till en tillgänglig port. I följande exempel visas hur du avgör vilken port Kestrel är bunden till vid körning.

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

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

        // ...
    }
});

Dynamisk bindning av en port är inte tillgänglig i vissa situationer:

• KestrelServerOptions.ListenLocalhost
• Bind TCP-baserad HTTP/1.1 eller HTTP/2 och QUIC-baserad HTTP/3 tillsammans.

Konfigurera HTTPS

Kestrel stöder skydd av slutpunkter med HTTPS. Data som skickas via HTTPS krypteras med Transport Layer Security (TLS) för att öka säkerheten för data som överförs mellan klienten och servern.

HTTPS kräver ett TLS-certifikat. TLS-certifikatet lagras på servern och Kestrel är konfigurerat att använda det. En app kan använda ASP.NET Core HTTPS-utvecklingscertifikatet i en lokal utvecklingsmiljö. Utvecklingscertifikatet är inte installerat i icke-utvecklingsmiljöer. I produktion måste ett TLS-certifikat konfigureras uttryckligen. Minst ett standardcertifikat måste tillhandahållas.

Hur HTTPS och TLS-certifikatet konfigureras beror på hur slutpunkter konfigureras:

• Om URL-prefix eller anger portar som endast används för att definiera slutpunkter, kan HTTPS endast användas om ett standardcertifikat anges i HTTPS-slutpunktskonfigurationen. Ett standardcertifikat kan konfigureras med något av följande alternativ:
• Konfigurera HTTPS i appsettings.json
• Konfigurera HTTPS i kod

Konfigurera HTTPS i appsettings.json

Ett standardkonfigurationsschema för HTTPS-appinställningar är tillgängligt för Kestrel. Konfigurera flera slutpunkter, inklusive URL:er och certifikat som ska användas, antingen från en fil på disk eller från ett certifikatarkiv.

Alla HTTPS-slutpunkter som inte anger ett certifikat (HttpsDefaultCert i exemplet nedan) återgår till certifikatet som definierats under Certificates:Default eller utvecklingscertifikatet.

Följande exempel är för appsettings.json, men alla konfigurationskällor kan användas:

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

Varning

I föregående exempel lagras certifikatlösenordet i klartext i appsettings.json. $CREDENTIAL_PLACEHOLDER$-token används som platshållare för certifikatets lösenord. Information om hur du lagrar certifikatlösenord på ett säkert sätt i utvecklingsmiljöer finns i Skydda hemligheter under utveckling. Information om hur du lagrar certifikatlösenord på ett säkert sätt i produktionsmiljöer finns i Azure Key Vault-konfigurationsprovidern. Utvecklingshemligheter bör inte användas för produktion eller testning.

Schemaanteckningar

• Slutpunktsnamn är skiftlägesokänsliga. Till exempel är HTTPS och Https likvärdiga.
• Parametern Url krävs för varje slutpunkt. Formatet för den här parametern är samma som den översta Urls konfigurationsparametern, förutom att den är begränsad till ett enda värde. Se URL-format tidigare i den här artikeln.
• Dessa slutpunkter ersätter de som definierats i den översta Urls konfigurationen i stället för att lägga till dem. Slutpunkter som definieras i kod via Listen är kumulativa med slutpunkterna som definieras i konfigurationsavsnittet.
• Avsnittet Certificate är valfritt. Om Certificate-avsnittet inte anges används standardvärdena som definieras i Certificates:Default. Om inga standardvärden är tillgängliga används utvecklingscertifikatet. Om det inte finns några standardvärden och utvecklingscertifikatet inte finns, utlöser servern ett undantag och startar inte.
• Avsnittet Certificate stöder flera certifikatkällor.
• Valfritt antal slutpunkter kan definieras i Configuration, så länge de inte orsakar portkonflikter.

Certifikatkällor

Certifikatnoder kan konfigureras för att läsa in certifikat från ett antal källor:

• Path och Password för att läsa in .pfx--filer.
• Path, KeyPath och Password för att läsa in .pem/.crt- och .key-filer.
• Subject och Store att läsa in från certifikatarkivet.

Till exempel kan Certificates:Default certifikat anges som:

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

Konfigurera klientcertifikat i appsettings.json

ClientCertificateMode används för att ställa in klientcertifikatets beteende.

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

Varning

I föregående exempel lagras certifikatlösenordet i klartext i appsettings.json. $CREDENTIAL_PLACEHOLDER$-token används som platshållare för certifikatets lösenord. Information om hur du lagrar certifikatlösenord på ett säkert sätt i utvecklingsmiljöer finns i Skydda hemligheter under utveckling. Information om hur du lagrar certifikatlösenord på ett säkert sätt i produktionsmiljöer finns i Azure Key Vault-konfigurationsprovidern. Utvecklingshemligheter bör inte användas för produktion eller testning.

Standardvärdet är ClientCertificateMode.NoCertificate, där Kestrel inte begär eller kräver ett certifikat från klienten.

Mer information finns i Konfigurera certifikatautentisering i ASP.NET Core.

Konfigurera SSL/TLS-protokoll i appsettings.json

SSL-protokoll är protokoll som används för att kryptera och dekryptera trafik mellan två peer-datorer, traditionellt en klient och en server.

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

Varning

I föregående exempel lagras certifikatlösenordet i klartext i appsettings.json. $CREDENTIAL_PLACEHOLDER$-token används som platshållare för certifikatets lösenord. Information om hur du lagrar certifikatlösenord på ett säkert sätt i utvecklingsmiljöer finns i Skydda hemligheter under utveckling. Information om hur du lagrar certifikatlösenord på ett säkert sätt i produktionsmiljöer finns i Azure Key Vault-konfigurationsprovidern. Utvecklingshemligheter bör inte användas för produktion eller testning.

Standardvärdet, SslProtocols.None, gör att Kestrel använder operativsystemets standardvärden för att välja det bästa protokollet. Om du inte har en specifik anledning att välja ett protokoll använder du standardvärdet.

Konfigurera HTTPS i kod

När du använder Listen-API:et är UseHttps-tilläggsmetoden på ListenOptions tillgänglig för att konfigurera HTTPS.

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

• filename är sökvägen och filnamnet för en certifikatfil i förhållande till katalogen som innehåller appens innehållsfiler.
• password är lösenordet som krävs för att komma åt X.509-certifikatdata.
• configureOptions är en Action för att konfigurera HttpsConnectionAdapterOptions. Returnerar ListenOptions.
• storeName är certifikatarkivet som certifikatet ska läsas in från.
• subject är certifikatets ämnesnamn.
• allowInvalid anger om ogiltiga certifikat ska beaktas, till exempel självsignerade certifikat.
• location är lagringsplatsen som certifikatet ska läsas in från.
• serverCertificate är X.509-certifikatet.

För en komplett lista över UseHttps överlagringar, se UseHttps.

Konfigurera klientcertifikat i kod

ClientCertificateMode konfigurerar kraven för klientcertifikatet.

var builder = WebApplication.CreateBuilder(args);

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

Standardvärdet är NoCertificate, där Kestrel inte begär eller kräver ett certifikat från klienten.

Mer information finns i Konfigurera certifikatautentisering i ASP.NET Core.

Konfigurera HTTPS-standardvärden i kod

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) anger en konfiguration Action som ska köras för varje HTTPS-slutpunkt. Om du anropar ConfigureHttpsDefaults flera gånger ersätts tidigare instanser av Action med den senaste angivna Action.

var builder = WebApplication.CreateBuilder(args);

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

Not

Slutpunkter som skapas genom att anropa Listeninnan anropar ConfigureHttpsDefaults har inte standardvärdena tillämpade.

Konfigurera SSL/TLS-protokoll i kod

SSL-protokoll är protokoll som används för att kryptera och dekryptera trafik mellan två peer-datorer, traditionellt en klient och en server.

var builder = WebApplication.CreateBuilder(args);

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

Konfigurera filtret för TLS-chiffersviter i kod

I Linux kan CipherSuitesPolicy användas för att filtrera TLS-handskakningar per anslutning:

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

Konfigurera servernamnsindikator

servernamnindikering (SNI) kan användas för att vara värd för flera domäner på samma IP-adress och port. SNI kan användas för att spara resurser genom att betjäna flera platser från en server.

För att SNI ska fungera skickar klienten värdnamnet för den säkra sessionen till servern under TLS-handskakningen så att servern kan tillhandahålla rätt certifikat. Klienten använder det tillhandahållna certifikatet för krypterad kommunikation med servern under den säkra sessionen som följer efter TLS-handskakningen.

Alla webbplatser måste köras på samma Kestrel instans. Kestrel stöder inte delning av en IP-adress och port över flera instanser utan omvänd proxy.

SNI kan konfigureras på två sätt:

• Konfigurera en mappning mellan värdnamn och HTTPS-alternativ i Configuration. Till exempel JSON i filen appsettings.json.
• Skapa en slutpunkt i kod och välj ett certifikat genom att använda värdnamnet med ServerCertificateSelector-återanrop.

Konfigurera SNI i appsettings.json

Kestrel stöder SNI som definierats i konfigurationen. En slutpunkt kan konfigureras med ett Sni objekt som innehåller en mappning mellan värdnamn och HTTPS-alternativ. Värdnamnet för anslutningen matchas med alternativen och används för just den anslutningen.

Följande konfiguration lägger till en slutpunkt med namnet MySniEndpoint som använder SNI för att välja HTTPS-alternativ baserat på värdnamnet:

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

Varning

I föregående exempel lagras certifikatlösenordet i klartext i appsettings.json. $CREDENTIAL_PLACEHOLDER$-token används som platshållare för certifikatets lösenord. Information om hur du lagrar certifikatlösenord på ett säkert sätt i utvecklingsmiljöer finns i Skydda hemligheter under utveckling. Information om hur du lagrar certifikatlösenord på ett säkert sätt i produktionsmiljöer finns i Azure Key Vault-konfigurationsprovidern. Utvecklingshemligheter bör inte användas för produktion eller testning.

HTTPS-alternativ som kan åsidosättas av SNI:

• Certificate konfigurerar certifikatkällan.
• Protocols konfigurerar tillåtna HTTP-protokoll.
• SslProtocols konfigurerar de tillåtna SSL-protokollen.
• ClientCertificateMode konfigurerar kraven för -klientcertifikatet.

Värdnamnet stöder jokerteckenmatchning:

• Exakt matchning. Till exempel matchar a.example.orga.example.org.
• Prefiks för jokertecken Om det finns flera jokerteckenmatchningar väljs det längsta mönstret. Till exempel matchar *.example.orgb.example.org och c.example.org.
• Fullständigt jokertecken. * matchar allt annat, inklusive klienter som inte använder SNI och inte skickar ett värdnamn.

Den matchade SNI-konfigurationen tillämpas på slutpunkten för anslutningen, vilket åsidosätter värden på slutpunkten. Om en anslutning inte matchar ett konfigurerat SNI-värdnamn nekas anslutningen.

Konfigurera SNI med kod

Kestrel stöder SNI med flera API:er för återanrop:

• ServerCertificateSelector
• ServerOptionsSelectionCallback
• TlsHandshakeCallbackOptions

SNI med ServerCertificateSelector

Kestrel stöder SNI genom ServerCertificateSelector återanrop. Återanropet anropas en gång per anslutning så att appen kan kontrollera värdnamnet och välja rätt certifikat:

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

Kestrel stöder ytterligare dynamisk TLS-konfiguration genom återanropet ServerOptionsSelectionCallback. Återanropet anropas en gång per anslutning så att appen kan inspektera värdnamnet och välja rätt certifikat- och TLS-konfiguration. Standardcertifikat och ConfigureHttpsDefaults används inte med det här återanropet.

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

Kestrel stöder ytterligare dynamisk TLS-konfiguration via TlsHandshakeCallbackOptions.OnConnection-återanropet. Återanropet anropas en gång per anslutning så att appen kan granska värdnamnet och välja rätt certifikat, TLS-konfiguration och andra serveralternativ. Standardcertifikat och ConfigureHttpsDefaults används inte med det här återanropet.

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

Konfigurera HTTP-protokoll

Kestrel stöder alla vanliga HTTP-versioner. Slutpunkter kan konfigureras för att stödja olika HTTP-versioner med hjälp av HttpProtocols uppräkning, som anger tillgängliga HTTP-versionsalternativ.

TLS krävs för att stödja mer än en HTTP-version. TLS Application-Layer Protocol Negotiation (ALPN) handskakning används för att förhandla om anslutningsprotokollet mellan klienten och servern när en slutpunkt stöder flera protokoll.

HttpProtocols värde	Anslutningsprotokoll godkänd
Http1	ENDAST HTTP/1.1. Kan användas med eller utan TLS.
Http2	Endast HTTP/2. Kan endast användas utan TLS om klienten stöder ett förhandskunskapsläge.
Http3	Endast HTTP/3. Kräver TLS. Klienten kan behöva konfigureras för att endast använda HTTP/3.
Http1AndHttp2	HTTP/1.1 och HTTP/2. HTTP/2 kräver att klienten väljer HTTP/2 i TLS Application-Layer Protocol Negotiation (ALPN) handskakning. Annars är anslutningen http/1.1 som standard.
Http1AndHttp2AndHttp3	HTTP/1.1, HTTP/2 och HTTP/3. Den första klientbegäran använder normalt HTTP/1.1 eller HTTP/2, och alt-svc-svarsrubriken uppmanar klienten att uppgradera till HTTP/3. HTTP/2 och HTTP/3 kräver TLS; Annars är anslutningen http/1.1 som standard.

Standardprotokollvärdet för en slutpunkt är HttpProtocols.Http1AndHttp2.

TLS-begränsningar för HTTP/2:

• TLS version 1.2 eller senare
• Omförhandling inaktiverad
• Komprimering har inaktiverats
• Minsta tillfälliga nyckelutbytesstorlekar:
  • Elliptisk kurva Diffie-Hellman (ECDHE) [RFC4492]: minst 224 bitar
  • Begränsat fält Diffie-Hellman (DHE) [TLS12]: minst 2 048 bitar
• Chiffersviten är inte förbjuden.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] med P-256 elliptisk kurva [FIPS186] stöds som standard.

Konfigurera HTTP-protokoll i appsettings.json

Följande appsettings.json exempel etablerar HTTP/1.1-anslutningsprotokollet för en specifik slutpunkt:

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

Ett standardprotokoll kan konfigureras i avsnittet Kestrel:EndpointDefaults. Följande appsettings.json exempel etablerar HTTP/1.1 som standardanslutningsprotokoll för alla slutpunkter:

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

Protokoll som anges i kod åsidosätter värden som sätts av konfigurationen.

Konfigurera HTTP-protokoll i kod

ListenOptions.Protocols används för att ange protokoll med HttpProtocols uppräkning.

I följande exempel konfigureras en slutpunkt för HTTP/1.1-, HTTP/2- och HTTP/3-anslutningar på port 8000. Anslutningar skyddas av TLS med ett angivet certifikat:

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

Se även

• Kestrel webbserver i ASP.NET Core
• Konfigurera alternativ för webbservern ASP.NET Core Kestrel