Konfigurace koncových bodů pro webový server ASP.NET Core Kestrel

Kestrel koncové body poskytují infrastrukturu pro naslouchání příchozím požadavkům a jejich směrování do příslušného middlewaru. Kombinace adresy a protokolu definuje koncový bod.

• Adresa určuje síťové rozhraní, na které server naslouchá příchozím požadavkům, jako je port TCP.
• Protokol určuje komunikaci mezi klientem a serverem, například HTTP/1.1, HTTP/2 nebo HTTP/3.
• Koncový bod je možné zabezpečit pomocí schématu https adresy URL nebo UseHttps metody.

Koncové body je možné nakonfigurovat pomocí adres URL, JSON v appsettings.jsona kódu. Tento článek popisuje použití jednotlivých možností ke konfiguraci koncového bodu:

• Konfigurace koncových bodů
• Konfigurace HTTPS
• Konfigurace protokolů HTTP

Výchozí koncový bod

Nové projekty ASP.NET Core jsou nakonfigurované tak, aby se svážely s náhodným portem HTTP mezi 5000–5300 a náhodným portem HTTPS mezi 7000–7300. Vybrané porty se ukládají do vygenerovaného Properties/launchSettings.json souboru a můžou je upravit vývojáři. Soubor launchSetting.json se používá pouze v místním vývoji.

Pokud neexistuje žádná konfigurace koncového bodu, vytvoří Kestrel vazbu na http://localhost:5000.

Konfigurace koncových bodů

Kestrel koncové body naslouchají příchozím připojením. Když se koncový bod vytvoří, musí být nakonfigurován pro adresu, na kterou bude naslouchat. Obvykle se jedná o adresu TCP a číslo portu.

Pro konfiguraci koncových bodů existuje několik možností:

• Konfigurace koncových bodů pomocí adres URL
• Zadat pouze porty
• Konfigurace koncových bodů v appsettings.json
• Konfigurace koncových bodů v kódu

Konfigurace koncových bodů pomocí adres URL

V následujících částech se dozvíte, jak nakonfigurovat koncové body pomocí následujících možností:

• ASPNETCORE_URLS proměnná prostředí.
• --urls argument příkazového řádku.
• urls konfigurační klíč hostitele.
• UseUrls rozšiřující metoda.
• WebApplication.Urls vlastnost.

Formáty adres URL

Adresy URL označují IP nebo hostitelské adresy s porty a protokoly, na které by měl server naslouchat. Port je možné vynechat, pokud se jedná o výchozí hodnotu protokolu (obvykle 80 a 443). Adresy URL můžou být v libovolném z následujících formátů.

• Adresa IPv4 s číslem portu

  http://65.55.39.10:80/
  

  0.0.0.0 je zvláštní případ, který se sváže se všemi adresami IPv4.

• Adresa IPv6 s číslem portu

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

  [::] je ekvivalentem IPv6 protokolu IPv4 0.0.0.0.

• Hostitel se zástupným znakem a číslem portu

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

  Cokoli, co se nerozpoznalo jako platná IP adresa nebo localhost se považuje za zástupný znak, který je vázán na všechny adresy IPv4 a IPv6. Někteří lidé rádi používají * nebo +, aby byli explicitnější. Pokud chcete svázat různé názvy hostitelů s různými aplikacemi ASP.NET Core na stejném portu, použijte HTTP.sys nebo reverzní proxy server.

  Příklady reverzního proxy serveru zahrnují IIS, YARP, Nginx a Apache.

• Název hostitele localhost s číslem portu nebo IP adresa se zpětnou smyčkou a číslem portu

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

  Po zadání localhost se Kestrel pokusí vytvořit vazbu na rozhraní zpětné smyčky IPv4 i IPv6. Pokud je požadovaný port používán jinou službou na některém z rozhraní zpětné smyčky, Kestrel se nepodaří spustit. Pokud je některé z rozhraní zpětné smyčky z jakéhokoli jiného důvodu nedostupné (nejčastěji kvůli tomu, že se nepodporuje protokol IPv6), Kestrel zaznamená upozornění.

Pomocí oddělovače středníku (;) je možné zadat více předpon adres URL:

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

Další informace naleznete v tématu Překonfigurace.

Předpony adresy URL HTTPS

Předpony adresy URL HTTPS je možné použít k definování koncových bodů pouze v případě, že je v konfiguraci koncového bodu HTTPS zadaný výchozí certifikát. Použijte KestrelServerOptions například konfiguraci nebo konfigurační soubor, jak je znázorněno dále v tomto článku.

Další informace najdete v tématu Konfigurace HTTPS.

Zadat pouze porty

Aplikace a kontejnery mají často jenom port pro naslouchání, jako je port 80, bez dalších omezení, jako je hostitel nebo cesta. HTTP_PORTS a HTTPS_PORTS jsou konfigurační klíče, které určují porty naslouchání pro Kestrel servery a servery HTTP.sys. Tyto klíče mohou být zadány jako proměnné prostředí definované s předponou DOTNET_ nebo ASPNETCORE_, anebo mohou být zadány přímo prostřednictvím jakéhokoli jiného vstupu konfigurace, například appsettings.json. Každý z nich je seznam hodnot portů oddělený středníkem, jak je znázorněno v následujícím příkladu:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Předchozí příklad je zkratka pro následující konfiguraci, která určuje schéma (HTTP nebo HTTPS) a libovolného hostitele nebo IP adresy.

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

Konfigurační klíče HTTP_PORTS a HTTPS_PORTS mají nižší prioritu a jsou přepsány adresami URL nebo hodnotami zadanými přímo v kódu. Certifikáty je stále potřeba nakonfigurovat samostatně prostřednictvím mechaniky specifické pro server pro PROTOKOL HTTPS.

Konfigurace koncových bodů v appsettings.json

Kestrel může načíst koncové body z IConfiguration instance. Ve výchozím nastavení se konfigurace Kestrel načte z oddílu Kestrel a koncové body se konfigurují v Kestrel:Endpoints:

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

Předchozí příklad:

• Používá se appsettings.json jako zdroj konfigurace. Lze však použít jakýkoli IConfiguration zdroj.
• Přidá koncový bod s názvem MyHttpEndpoint na portu 8080.

Další informace o konfiguraci koncových bodů pomocí formátu JSON najdete v dalších částech tohoto článku, které diskutují o konfiguraci protokolu HTTPS a konfiguraci protokolů HTTP v appsettings.json.

Opětovné načtení koncových bodů z konfigurace

Opětovné načtení konfigurace koncového bodu, když je ve výchozím nastavení povolená změna zdroje konfigurace. Lze ho zakázat pomocí KestrelServerOptions.Configure(IConfiguration, Boolean).

Pokud je změna signalována, provede se následující kroky:

• Nová konfigurace se porovná se starou konfigurací a žádný koncový bod bez změn konfigurace se nezmění.
• Odebrané nebo upravené koncové body mají 5 sekund k dokončení požadavků na zpracování a vypnutí.
• Spustí se nové nebo upravené koncové body.

Klienti, kteří se připojují k upravenému koncovému bodu, můžou být při restartování koncového bodu odpojeni nebo odmítnuti.

Načítání konfigurace

KestrelServerOptions.Configure vrátí hodnotu KestrelConfigurationLoader. Metoda zavaděče Endpoint(String, Action<EndpointConfiguration>), kterou lze použít k doplnění nakonfigurovaných nastavení koncového bodu:

var builder = WebApplication.CreateBuilder(args);

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

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

KestrelServerOptions.ConfigurationLoader lze přímo přistoupit k tomu, abyste mohli pokračovat v iteraci na existujícím zavaděči, jako je například ten, který poskytuje WebApplicationBuilder.WebHost.

• Konfigurační část pro každý koncový bod je dostupná v možnostech metody Endpoint, aby mohla být načtena vlastní nastavení.
• KestrelServerOptions.Configure(IConfiguration) lze volat vícekrát, ale pouze poslední konfigurace je použita, pokud Load není explicitně volána u předchozích instancí. Výchozí hostitel nevolá Load , aby se jeho výchozí konfigurační oddíl mohl nahradit.
• KestrelConfigurationLoader zrcadlí Listen řadu rozhraní API z KestrelServerOptionsEndpoint přetížení, takže koncové body kódu a konfigurace je možné nakonfigurovat na stejném místě. Tato přetížení nepoužívají názvy a využívají pouze výchozí nastavení z konfigurace.

Konfigurace koncových bodů v kódu

KestrelServerOptions poskytuje metody konfigurace koncových bodů v kódu:

• Listen
• ListenLocalhost
• ListenAnyIP
• ListenUnixSocket
• ListenNamedPipe

Listen Když se současně použijí rozhraní API UseUrls, Listen přepíší UseUrls koncové body.

Vytvoření vazby k soketu TCP

Metody Listen, ListenLocalhost a ListenAnyIP se vážou na soket TCP:

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

Předchozí příklad:

• Konfiguruje koncové body, které naslouchají na portu 5000 a 5001.
• Nakonfiguruje HTTPS pro koncový bod pomocí metody rozšíření UseHttps na ListenOptions. Další informace najdete v tématu Konfigurace HTTPS v kódu.

Ve Windows je možné vytvořit samo podepsané certifikáty pomocí rutiny PowerShellNew-SelfSignedCertificate. Nepodporovaný příklad naleznete na UpdateIISExpressSSLForChrome.ps1.

V systémech macOS, Linux a Windows je možné certifikáty vytvářet pomocí OpenSSL.

Připojit na unixový soket

Naslouchejte na soketu Unix s lepším výkonem ListenUnixSocket pomocí Nginx, jak je znázorněno v tomto příkladu:

var builder = WebApplication.CreateBuilder(args);

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

• V konfiguračním souboru Nginx nastavte server>location>proxy_passpoložku na .http://unix:/tmp/{KESTREL SOCKET}:/; {KESTREL SOCKET} je název zadaného soketu ListenUnixSocket (například kestrel-test.sock v předchozím příkladu).
• Ujistěte se, že je soket zapisovatelný pomocí Nginx (například chmod go+w /tmp/kestrel-test.sock).

Konfigurace výchozích hodnot koncového bodu

ConfigureEndpointDefaults(Action<ListenOptions>) určuje konfiguraci, která se spouští pro každý zadaný koncový bod. Volání ConfigureEndpointDefaults několikrát nahrazuje předchozí konfiguraci.

var builder = WebApplication.CreateBuilder(args);

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

Poznámka:

Koncové body vytvořené voláním Listenpřed voláním ConfigureEndpointDefaults nebudou mít použité výchozí hodnoty.

Dynamická vazba portu

Pokud je zadáno číslo 0 portu, Kestrel dynamicky vytvoří vazbu k dostupnému portu. Následující příklad ukazuje, jak určit port Kestrel vázaný za běhu:

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

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

        // ...
    }
});

Dynamická vazba portu není v některých situacích dostupná:

• KestrelServerOptions.ListenLocalhost
• Propojování HTTP/1.1 a HTTP/2 založených na TCP a HTTP/3 založeného na QUIC.

Konfigurace HTTPS

Kestrel podporuje zabezpečení koncových bodů pomocí protokolu HTTPS. Data odesílaná přes PROTOKOL HTTPS se šifrují pomocí protokolu TLS (Transport Layer Security), aby se zvýšilo zabezpečení dat přenášených mezi klientem a serverem.

HTTPS vyžaduje certifikát TLS. Certifikát TLS je uložený na serveru a Kestrel je nakonfigurovaný tak, aby ho používal. Aplikace může používat vývojový certifikát ASP.NET Core HTTPS v místním vývojovém prostředí. Vývojový certifikát není nainstalovaný v prostředích, která nejsou součástí vývoje. V produkčním prostředí musí být certifikát TLS explicitně nakonfigurovaný. Je nutné poskytnout alespoň výchozí certifikát.

Způsob konfigurace protokolu HTTPS a certifikátu TLS závisí na konfiguraci koncových bodů:

• Pokud se k definování koncových bodů používají předpony adres URL nebo pouze zadání portů, lze HTTPS použít jen tehdy, pokud je v konfiguraci koncového bodu HTTPS uveden výchozí certifikát. Výchozí certifikát lze nakonfigurovat s jednou z následujících možností:
• Konfigurovat HTTPS v appsettings.json
• Konfigurace HTTPS v kódu

Konfigurace HTTPS v appsettings.json

Pro nastavení aplikace HTTPS je k dispozici výchozí schéma konfigurace pro Kestrel. Nakonfigurujte několik koncových bodů, včetně adres URL a certifikátů, které se mají použít, a to buď ze souboru na disku, nebo z úložiště certifikátů.

Jakýkoli koncový bod HTTPS, který neurčuje certifikát (HttpsDefaultCert v následujícím příkladu), se vrátí k certifikátu definovanému v rámci Certificates:Default nebo vývojovém certifikátu.

Následující příklad je pro appsettings.json, ale jakýkoli zdroj konfigurace lze použít:

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

Varování

V předchozím příkladu je heslo certifikátu uloženo ve formátu prostého textu .appsettings.json Token $CREDENTIAL_PLACEHOLDER$ se používá jako zástupný symbol pro heslo certifikátu. Pokud chcete bezpečně ukládat hesla certifikátů ve vývojových prostředích, přečtěte si téma Ochrana tajných kódů při vývoji. Pokud chcete bezpečně ukládat hesla certifikátů v produkčních prostředích, přečtěte si o poskytovateli konfigurace služby Azure Key Vault. Tajné kódy pro vývoj by se neměly používat pro produkční ani testovací prostředí.

Poznámky ke schématu

• Názvy koncových bodů nerozlišují malá a velká písmena. Například HTTPS a Https jsou ekvivalentní.
• Parametr Url se vyžaduje pro každý koncový bod. Formát tohoto parametru je stejný jako konfigurační parametr nejvyšší úrovně Urls s tím rozdílem, že je omezený na jednu hodnotu. Viz formáty adres URL dříve v tomto článku.
• Tyto koncové body nahrazují ty, které jsou definované v konfiguraci nejvyšší úrovně Urls, nikoli jejich přidáním. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v konfigurační části.
• Oddíl Certificate je nepovinný. Pokud není zadaný oddíl v Certificate, použijí se výchozí hodnoty definované v oddílu Certificates:Default. Pokud nejsou k dispozici žádné výchozí hodnoty, použije se vývojový certifikát. Pokud neexistují žádné výchozí hodnoty a není k dispozici vývojový certifikát, server vyvolá výjimku a nespustí se.
• Tato Certificate část podporuje více zdrojů certifikátů.
• Libovolný počet koncových bodů může být definován v Configurationpřípadě, že nezpůsobují konflikty portů.

Zdroje certifikátů

Uzly certifikátů je možné nakonfigurovat tak, aby načítá certifikáty z řady zdrojů:

• Path a Password načíst soubory .pfx .
• Path, KeyPath a Password k načtení souborů .pem, .crt a .key.
• Subject a Store z úložiště certifikátů načíst.

Certificates:Default Například certifikát lze zadat takto:

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

Konfigurace klientských certifikátů v appsettings.json

ClientCertificateMode slouží ke konfiguraci chování klientského certifikátu.

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

Varování

V předchozím příkladu je heslo certifikátu uloženo ve formátu prostého textu .appsettings.json Token $CREDENTIAL_PLACEHOLDER$ se používá jako zástupný symbol pro heslo certifikátu. Pokud chcete bezpečně ukládat hesla certifikátů ve vývojových prostředích, přečtěte si téma Ochrana tajných kódů při vývoji. Pokud chcete bezpečně ukládat hesla certifikátů v produkčních prostředích, přečtěte si o poskytovateli konfigurace služby Azure Key Vault. Tajné kódy pro vývoj by se neměly používat pro produkční ani testovací prostředí.

Výchozí hodnota je ClientCertificateMode.NoCertificate, kde Kestrel nevyžaduje nebo nevyžaduje certifikát od klienta.

Další informace najdete v tématu Konfigurace ověřování certifikátů v ASP.NET Core.

Konfigurace protokolů SSL/TLS v appsettings.json

Protokoly SSL jsou protokoly používané k šifrování a dešifrování provozu mezi dvěma uzly, obvykle mezi klientem a serverem.

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

Varování

V předchozím příkladu je heslo certifikátu uloženo ve formátu prostého textu .appsettings.json Token $CREDENTIAL_PLACEHOLDER$ se používá jako zástupný symbol pro heslo certifikátu. Pokud chcete bezpečně ukládat hesla certifikátů ve vývojových prostředích, přečtěte si téma Ochrana tajných kódů při vývoji. Pokud chcete bezpečně ukládat hesla certifikátů v produkčních prostředích, přečtěte si o poskytovateli konfigurace služby Azure Key Vault. Tajné kódy pro vývoj by se neměly používat pro produkční ani testovací prostředí.

Výchozí hodnota SslProtocols.None umožní Kestrel použít výchozí nastavení operačního systému, aby zvolil nejlepší protokol. Pokud nemáte konkrétní důvod k výběru protokolu, použijte výchozí nastavení.

Konfigurace HTTPS v kódu

Při použití rozhraní API Listen je k dispozici metoda rozšíření UseHttps na ListenOptions pro konfiguraci 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 parametry:

• filename je cesta a název souboru certifikátu vzhledem k adresáři, který obsahuje soubory obsahu aplikace.
• password je heslo potřebné pro přístup k datům certifikátu X.509.
• configureOptions je Action pro konfiguraci HttpsConnectionAdapterOptions. Vrátí hodnotu ListenOptions.
• storeName je úložiště certifikátů, ze kterého se má certifikát načíst.
• subject je název subjektu certifikátu.
• allowInvalid označuje, zda by se měly považovat za neplatné certifikáty, jako jsou certifikáty podepsané svým držitelem.
• location je umístění úložiště, ze které se má certifikát načíst.
• serverCertificate je certifikát X.509.

Úplný seznam UseHttps přetížení najdete v sekci UseHttps.

Konfigurace klientských certifikátů v kódu

ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

var builder = WebApplication.CreateBuilder(args);

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

Výchozí hodnota je NoCertificate, kde Kestrel nevyžaduje nebo nevyžaduje certifikát od klienta.

Další informace najdete v tématu Konfigurace ověřování certifikátů v ASP.NET Core.

Konfigurace výchozích hodnot HTTPS v kódu

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) určuje konfiguraci Action , která se má spustit pro každý koncový bod HTTPS. Volání ConfigureHttpsDefaults několikrát nahradí předchozí instance Action poslední zadanou instancí Action.

var builder = WebApplication.CreateBuilder(args);

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

Poznámka:

Koncové body vytvořené voláním Listenpřed voláním ConfigureHttpsDefaults nebudou mít použité výchozí hodnoty.

Konfigurace protokolů SSL/TLS v kódu

Protokoly SSL jsou protokoly používané k šifrování a dešifrování provozu mezi dvěma uzly, tradičně klientem a serverem.

var builder = WebApplication.CreateBuilder(args);

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

Konfigurace filtru šifrovacích sad TLS v kódu

Na Linuxu lze CipherSuitesPolicy použít k filtrování handshake protokolu TLS pro jednotlivá připojení:

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

Konfigurace indikace názvu serveru

Indikaci názvu serveru (SNI) lze použít k hostování více domén na stejné IP adrese a portu. SNI lze použít k zachování prostředků obsluhou více lokalit z jednoho serveru.

Aby rozhraní SNI fungovalo, klient odešle název hostitele pro zabezpečenou relaci na server během metody handshake protokolu TLS, aby server mohl poskytnout správný certifikát. Klient používá zařízený certifikát pro šifrovanou komunikaci se serverem během zabezpečené relace, která následuje za metodou handshake protokolu TLS.

Všechny weby musí běžet ve stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu mezi více instancemi bez reverzního proxy serveru.

SNI je možné nakonfigurovat dvěma způsoby:

• Nakonfigurujte mapování mezi názvy hostitelů a možnostmi HTTPS v konfiguraci. Například JSON v appsettings.json souboru.
• Vytvořte koncový bod v kódu a vyberte certifikát pomocí názvu hostitele se zpětným voláním ServerCertificateSelector .

Konfigurace SNI v appsettings.json

Kestrel podporuje SNI definované v konfiguraci. Koncový bod lze nakonfigurovat s objektem Sni , který obsahuje mapování mezi názvy hostitelů a možnostmi HTTPS. Název hostitele připojení se shoduje s možnostmi a používá se pro toto připojení.

Následující konfigurace přidá koncový bod pojmenovaný MySniEndpoint, který používá SNI k výběru možností HTTPS na základě názvu hostitele.

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

Upozornění

V předchozím příkladu je heslo certifikátu uloženo ve formátu prostého textu .appsettings.json Token $CREDENTIAL_PLACEHOLDER$ se používá jako zástupný symbol pro heslo certifikátu. Pokud chcete bezpečně ukládat hesla certifikátů ve vývojových prostředích, přečtěte si téma Ochrana tajných kódů při vývoji. Pokud chcete bezpečně ukládat hesla certifikátů v produkčních prostředích, přečtěte si o poskytovateli konfigurace služby Azure Key Vault. Tajné kódy pro vývoj by se neměly používat pro produkční ani testovací prostředí.

Možnosti HTTPS, které je možné přepsat pomocí SNI:

• Certificate nakonfiguruje zdroj certifikátu.
• Protocols nakonfiguruje povolené protokoly HTTP.
• SslProtocols nakonfiguruje povolené protokoly SSL.
• ClientCertificateMode nakonfiguruje požadavky na klientský certifikát.

Název hostitele podporuje porovnávání zástupných znaků:

• Přesná shoda. Například a.example.org odpovídá a.example.org.
• Předpona zástupných znaků. Pokud existuje více shod pro zástupné symboly, vybere se nejdelší vzorec. Například *.example.org odpovídá b.example.org a c.example.org.
• Úplný wildcard. * odpovídá všemu jinému, včetně klientů, kteří nepoužívají SNI a neposílají název hostitele.

Odpovídající konfigurace SNI se aplikuje na koncový bod pro připojení a přepíše hodnoty na koncovém bodu. Pokud se připojení neshoduje s nakonfigurovaným názvem hostitele SNI, připojení se odmítne.

Konfigurace SNI pomocí kódu

Kestrel podporuje SNI s několika rozhraními API zpětného volání:

• ServerCertificateSelector
• ServerOptionsSelectionCallback
• TlsHandshakeCallbackOptions

SNI s ServerCertificateSelector

Kestrel podporuje SNI prostřednictvím ServerCertificateSelector callback. Zpětné volání se vyvolá jednou za připojení, aby aplikace mohla zkontrolovat název hostitele a vybrat příslušný certifikát:

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

Kestrel podporuje další dynamickou konfiguraci protokolu TLS prostřednictvím zpětného ServerOptionsSelectionCallback volání. Zpětné volání se vyvolá jednou za připojení, aby aplikace mohla zkontrolovat název hostitele a vybrat odpovídající certifikát a konfiguraci protokolu TLS. Výchozí certifikáty a ConfigureHttpsDefaults nepoužívají se s tímto zpětným voláním.

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

Kestrel podporuje další dynamickou konfiguraci protokolu TLS prostřednictvím zpětného TlsHandshakeCallbackOptions.OnConnection volání. Zpětné volání se vyvolá jednou za připojení, aby aplikace mohla zkontrolovat název hostitele a vybrat příslušný certifikát, konfiguraci protokolu TLS a další možnosti serveru. Výchozí certifikáty a ConfigureHttpsDefaults nepoužívají se s tímto zpětným voláním.

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

Konfigurace protokolů HTTP

Kestrel podporuje všechny běžně používané verze HTTP. Koncové body je možné nakonfigurovat tak, aby podporovaly různé verze HTTP pomocí výčtu HttpProtocols , který určuje dostupné možnosti verze PROTOKOLU HTTP.

Pro podporu více než jedné verze PROTOKOLU HTTP se vyžaduje protokol TLS. Metoda handshake protokolu TLS Application-Layer Protocol (ALPN) se používá k vyjednávání protokolu připojení mezi klientem a serverem, když koncový bod podporuje více protokolů.

HttpProtocols hodnota	Povolený protokol připojení
Http1	Pouze HTTP/1.1. Lze použít s protokolem TLS nebo bez protokolu TLS.
Http2	Pouze HTTP/2. Lze použít bez protokolu TLS pouze v případě, že klient podporuje předchozí režim znalostí.
Http3	Pouze HTTP/3. Vyžaduje protokol TLS. Klient možná bude muset být nakonfigurovaný tak, aby používal pouze HTTP/3.
Http1AndHttp2	HTTP/1.1 a HTTP/2. HTTP/2 vyžaduje, aby klient vybral HTTP/2 v handshake TLS Application-Layer Protocol Negotiation (ALPN); jinak se připojení ve výchozím nastavení přepne na HTTP/1.1.
Http1AndHttp2AndHttp3	HTTP/1.1, HTTP/2 a HTTP/3. První požadavek klienta obvykle používá http/1.1 nebo HTTP/2 a alt-svc hlavička odpovědi vyzve klienta k upgradu na HTTP/3. PROTOKOL HTTP/2 a HTTP/3 vyžaduje protokol TLS; jinak se ve výchozím nastavení připojení nastaví na HTTP/1.1.

Výchozí hodnota protokolu pro koncový bod je HttpProtocols.Http1AndHttp2.

Omezení protokolu TLS pro HTTP/2:

• TLS verze 1.2 nebo novější
• Opětovné vyjednávání zakázáno
• Komprese zakázána
• Minimální dočasné velikosti výměny klíčů:
  • Elliptic curve Diffie-Hellman (ECDHE) [RFC4492]: minimálně 224 bitů
  • Konečné pole Diffie-Hellman (DHE) [TLS12]: minimálně 2048 bitů
• Šifrovací sada není zakázaná.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] s eliptickou křivkou P-256 [FIPS186] je ve výchozím nastavení podporována.

Konfigurace protokolů HTTP v appsettings.json

Následující appsettings.json příklad vytvoří protokol připojení HTTP/1.1 pro konkrétní koncový bod:

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

V oddílu Kestrel:EndpointDefaults je možné nakonfigurovat výchozí protokol. Následující appsettings.json příklad vytvoří http/1.1 jako výchozí připojovací protokol pro všechny koncové body:

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

Protokoly zadané v kódu přepisují hodnoty nastavené konfigurací.

Konfigurace protokolů HTTP v kódu

ListenOptions.Protocols slouží k určení protokolů pomocí výčtu HttpProtocols .

Následující příklad nakonfiguruje koncový bod pro připojení HTTP/1.1, HTTP/2 a HTTP/3 na portu 8000. Připojení jsou zabezpečená protokolem TLS se zadaným certifikátem:

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

Přizpůsobení Kestrel koncových bodů pojmenovaného kanálu

Podpora pojmenovaných kanálů v Kestrelzahrnuje pokročilé možnosti přizpůsobení. Vlastnost CreateNamedPipeServerStream u pojmenovaných kanálů umožňuje přizpůsobení kanálů podle koncového bodu.

To je užitečné například v aplikaci Kestrel, která vyžaduje dva koncové body potrubí s různým zabezpečením přístupu . Možnost CreateNamedPipeServerStream lze použít k vytváření kanálů s vlastním nastavením zabezpečení v závislosti na názvu kanálu.

using System.IO.Pipes;
using System.Security.AccessControl;
using System.Security.Principal;

var builder = WebApplication.CreateBuilder();

builder.WebHost.ConfigureKestrel(options =>
{
    options.ListenNamedPipe("defaultPipe");
    options.ListenNamedPipe("securedPipe");
});

builder.WebHost.UseNamedPipes(options =>
{
    options.CreateNamedPipeServerStream = (context) =>
    {
        var pipeName = context.NamedPipeEndPoint.PipeName;
        
        switch (pipeName)
        {
            case "defaultPipe":
                return NamedPipeTransportOptions.CreateDefaultNamedPipeServerStream(context);
            case "securedPipe":
                var allowSecurity = new PipeSecurity();
                allowSecurity.AddAccessRule(new PipeAccessRule("Users", PipeAccessRights.FullControl, AccessControlType.Allow));

                return NamedPipeServerStreamAcl.Create(pipeName, PipeDirection.InOut,
                    NamedPipeServerStream.MaxAllowedServerInstances, PipeTransmissionMode.Byte,
                    context.PipeOptions, inBufferSize: 0, outBufferSize: 0, allowSecurity);
            default:
                throw new InvalidOperationException($"Unexpected pipe name: {pipeName}");
        }
    };
});

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

Viz také

• Kestrel webový server v ASP.NET Core
• Konfigurace možností webového serveru ASP.NET Core Kestrel