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 nakonfigurovaný s adresou, 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ými čísly portů

  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 + jsou 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 localhost hostitele s číslem portu nebo IP adresou zpětné smyčky s číslem portu

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

  Po localhost zadání Kestrel se pokusí vytvořit vazbu na rozhraní zpětné smyčky IPv4 i IPv6. Pokud požadovaný port používá jiná služba v jiném rozhraní zpětné smyčky, Kestrel nepodaří se 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řepsání konfigurace.

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 DOTNET_ předponami nebo ASPNETCORE_ zadané 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í Kestrel se konfigurace 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á appsettings.json se 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.

ConfigurationLoader

KestrelServerOptions.Configure vrátí hodnotu KestrelConfigurationLoader. Metoda zavaděče Endpoint(String, Action<EndpointConfiguration>) , která se dá použít k doplnění nakonfigurovaného 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 získat přímý přístup k pokračování iterace v existujícím zavaděče, jako je například ten, který WebApplicationBuilder.WebHostposkytuje .

• Oddíl konfigurace pro každý koncový bod je k dispozici v možnostech v Endpoint metodě, aby bylo možné číst 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 KestrelServerOptions Endpoint 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 i UseUrls, Listen přepíší UseUrls koncové body koncové body.

Vytvoření vazby k soketu TCP

Metody Listena , ListenLocalhostkteré ListenAnyIP jsou svázané se soketem 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í UseHttps metody rozšíření .ListenOptions Další informace najdete v tématu Konfigurace HTTPS v kódu.

Ve Windows je možné vytvořit certifikáty podepsané svým držitelem pomocí rutiny PowerShellu.New-SelfSignedCertificate Nepodporovaný příklad najdete v tématu UpdateIISExpressSSLForChrome.ps1.

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

Vytvoření vazby k soketu Unix

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>proxy_pass>locationpolož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 Listen př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
• Vazby PROTOKOLU HTTP/1.1 nebo HTTP/2 založené na protokolu TCP a vzájemně založené na QUIC HTTP/3.

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ý. Musí se zadat minimálně 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í jenom předpony adres URL nebo zadání portů, můžete https použít jenom v případě, že je v konfiguraci koncového bodu HTTPS zadaný výchozí certifikát. Výchozí certifikát lze nakonfigurovat s jednou z následujících možností:
• Konfigurace HTTPS v appsettings.json
• Konfigurace HTTPS v kódu

Konfigurace HTTPS v appsettings.json

Pro nastavení aplikace HTTPS je k dispozici Kestrelvýchozí schéma konfigurace nastavení aplikace HTTPS . 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$"
      }
    }
  }
}

Upozorňující

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 , a ne jejich přidávání. 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ý. Certificate Pokud není zadaný oddíl, použijí se výchozí hodnoty definované v Certificates:Default oddílu. 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 .
• PathKeyPath a Password pro načtení souborů .pem.crt/ a .key.
• Subject a Store načíst z úložiště certifikátů.

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

Upozorňující

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 partnerskými vztahy, tradičně klientem a serverem.

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

Upozorňující

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.Nonezpůsobí Kestrel použití výchozího operačního systému zvolit 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í Listen rozhraní API UseHttps je k dispozici metoda ListenOptions rozšíření 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 konfigurace Action 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í naleznete v tématu 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í Action instance poslední Action zadanou instancí.

var builder = WebApplication.CreateBuilder(args);

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

Poznámka:

Koncové body vytvořené voláním Listen př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 partnerskými vztahy, 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

V Linuxu CipherSuitesPolicy je možné použít k filtrování metod handshake protokolu TLS na základě 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 s názvem MySniEndpoint 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$"
      }
    }
  }
}

Upozorňující

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 zástupných znaků, vybere se nejdelší vzor. Například *.example.org shody b.example.org a c.example.org.
• Plný zástupný znak. * 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 použije na koncový bod pro připojení a přepisuje hodnoty koncového 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 zpětného ServerCertificateSelector 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:

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. PROTOKOL HTTP/2 vyžaduje, aby klient vybral protokol HTTP/2 v metodě handshake protokolu TLS Application-Layer Protocol (ALPN), jinak se ve výchozím nastavení připojení nastaví 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 je zakázaná
• 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 hodnotách přepsání kódu nastavených 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;
    });
});

Viz také

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