Konfigurowanie punktów końcowych dla serwera internetowego ASP.NET Core Kestrel

Kestrel punkty końcowe zapewniają infrastrukturę do nasłuchiwania żądań przychodzących i kierowania ich do odpowiedniego oprogramowania pośredniczącego. Kombinacja adresu i protokołu definiuje punkt końcowy.

• Adres określa interfejs sieciowy, na który serwer nasłuchuje dla żądań przychodzących, takich jak port TCP.
• Protokół określa komunikację między klientem a serwerem, takim jak HTTP/1.1, HTTP/2 lub HTTP/3.
• Punkt końcowy można zabezpieczyć przy użyciu schematu https adresu URL lub UseHttps metody.

Punkty końcowe można skonfigurować przy użyciu adresów URL, JSON w appsettings.jsonkodzie i . W tym artykule omówiono sposób konfigurowania punktu końcowego przy użyciu każdej opcji:

• Konfigurowanie punktów końcowych
• Konfigurowanie protokołu HTTPS
• Konfigurowanie protokołów HTTP

Domyślny punkt końcowy

Nowe projekty ASP.NET Core są skonfigurowane do powiązania z losowym portem HTTP z zakresu od 5000 do 5300 i losowego portu HTTPS z zakresu od 7000 do 7300. Wybrane porty są przechowywane w wygenerowanym Properties/launchSettings.json pliku i mogą być modyfikowane przez dewelopera. Plik launchSetting.json jest używany tylko w środowisku lokalnym.

Jeśli nie ma konfiguracji punktu końcowego, powiąże się Kestrel z http://localhost:5000.

Konfigurowanie punktów końcowych

Kestrel punkty końcowe nasłuchują połączeń przychodzących. Po utworzeniu punktu końcowego należy go skonfigurować przy użyciu adresu, na który będzie nasłuchiwać. Zazwyczaj jest to adres TCP i numer portu.

Istnieje kilka opcji konfigurowania punktów końcowych:

• Konfigurowanie punktów końcowych przy użyciu adresów URL
• Określanie tylko portów
• Konfigurowanie punktów końcowych w appsettings.json
• Konfigurowanie punktów końcowych w kodzie

Konfigurowanie punktów końcowych przy użyciu adresów URL

W poniższych sekcjach opisano sposób konfigurowania punktów końcowych przy użyciu polecenia :

• ASPNETCORE_URLS zmienna środowiskowa.
• --urls argument wiersza polecenia.
• urls klucz konfiguracji hosta.
• UseUrls metoda rozszerzenia.
• WebApplication.Urls własność.

Formaty adresów URL

Adresy URL wskazują adresy IP lub hosty z portami i protokołami, na których serwer powinien nasłuchiwać. Port można pominąć, jeśli jest to domyślny dla protokołu (zazwyczaj 80 i 443). Adresy URL mogą mieć dowolny z następujących formatów.

• Adres IPv4 z numerem portu

  http://65.55.39.10:80/
  

  0.0.0.0 Jest to specjalny przypadek, który wiąże się ze wszystkimi adresami IPv4.

• Adres IPv6 z numerem portu

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

  [::] to odpowiednik protokołu IPv6 protokołu IPv4 0.0.0.0.

• Host z symbolami wieloznacznymi z numerem portu

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

  Wszystkie elementy nie rozpoznane jako prawidłowy adres IP lub localhost są traktowane jako symbol wieloznaczny, który wiąże się ze wszystkimi adresami IPv4 i IPv6. Niektóre osoby lubią używać * lub + być bardziej wyraźne. Aby powiązać różne nazwy hostów z różnymi aplikacjami ASP.NET Core na tym samym porcie, użyj HTTP.sys lub odwrotnego serwera proxy.

  Przykłady odwrotnego serwera proxy obejmują usługi IIS, YARP, Nginx i Apache.

• Nazwa localhost hosta z numerem portu lub adresem IP sprzężenia zwrotnego z numerem portu

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

  Gdy localhost zostanie określony, Kestrel próbuje powiązać zarówno interfejsy IPv4, jak i IPv6 sprzężenia zwrotnego. Jeśli żądany port jest używany przez inną usługę w interfejsie sprzężenia zwrotnego, Kestrel nie można uruchomić. Jeśli którykolwiek z interfejsów sprzężenia zwrotnego jest niedostępny z jakiegokolwiek innego powodu (najczęściej dlatego, że protokół IPv6 nie jest obsługiwany), Kestrel rejestruje ostrzeżenie.

Wiele prefiksów adresów URL można określić za pomocą ogranicznika średnika (;):

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

Aby uzyskać więcej informacji, zobacz Zastępowanie konfiguracji.

Prefiksy adresów URL protokołu HTTPS

Prefiksy adresów URL protokołu HTTPS mogą służyć do definiowania punktów końcowych tylko wtedy, gdy w konfiguracji punktu końcowego HTTPS podano domyślny certyfikat. Na przykład użyj KestrelServerOptions konfiguracji lub pliku konfiguracji, jak pokazano w dalszej części tego artykułu.

Aby uzyskać więcej informacji, zobacz Konfigurowanie protokołu HTTPS.

Określanie tylko portów

Aplikacje i kontenery często otrzymują tylko port do nasłuchiwania, na przykład port 80, bez dodatkowych ograniczeń, takich jak host lub ścieżka. HTTP_PORTS i HTTPS_PORTS to klucze konfiguracji, które określają porty nasłuchiwania dla Kestrel serwerów i HTTP.sys. Te klucze można określić jako zmienne środowiskowe zdefiniowane za pomocą DOTNET_ prefiksów lub ASPNETCORE_ lub określone bezpośrednio za pomocą innych danych wejściowych konfiguracji, takich jak appsettings.json. Każda z nich jest rozdzieloną średnikami listą wartości portów, jak pokazano w poniższym przykładzie:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

Powyższy przykład jest skrócony dla następującej konfiguracji, która określa schemat (HTTP lub HTTPS) i dowolny host lub adres IP.

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

Klucze konfiguracji HTTP_PORTS i HTTPS_PORTS mają niższy priorytet i są zastępowane przez adresy URL lub wartości podane bezpośrednio w kodzie. Certyfikaty nadal muszą być konfigurowane oddzielnie za pośrednictwem mechaniki specyficznej dla serwera dla protokołu HTTPS.

Konfigurowanie punktów końcowych w appsettings.json

Kestrel może ładować punkty końcowe z IConfiguration wystąpienia. Domyślnie Kestrel konfiguracja jest ładowana z Kestrel sekcji, a punkty końcowe są konfigurowane w programie Kestrel:Endpoints:

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

Powyższy przykład:

• Używa appsettings.json jako źródła konfiguracji. Można jednak użyć dowolnego IConfiguration źródła.
• Dodaje punkt końcowy o nazwie MyHttpEndpoint na porcie 8080.

Aby uzyskać więcej informacji na temat konfigurowania punktów końcowych przy użyciu formatu JSON, zobacz sekcje w dalszej części tego artykułu, w których omówiono konfigurowanie protokołów HTTPS i konfigurowanie protokołów HTTP w appsettings.json.

Ponowne ładowanie punktów końcowych z konfiguracji

Ponowne ładowanie konfiguracji punktu końcowego, gdy źródło konfiguracji zostanie domyślnie włączone. Można go wyłączyć przy użyciu polecenia KestrelServerOptions.Configure(IConfiguration, Boolean).

Jeśli zostanie zasygnalizowana zmiana, zostaną wykonane następujące czynności:

• Nowa konfiguracja jest porównywana ze starym, a żaden punkt końcowy bez zmian konfiguracji nie jest modyfikowany.
• Usunięte lub zmodyfikowane punkty końcowe mają 5 sekund na ukończenie przetwarzania żądań i zamknięcie.
• Uruchomiono nowe lub zmodyfikowane punkty końcowe.

Klienci łączący się z zmodyfikowanym punktem końcowym mogą zostać rozłączone lub odrzucone podczas ponownego uruchamiania punktu końcowego.

ConfigurationLoader

KestrelServerOptions.Configure zwraca wartość KestrelConfigurationLoader. Metoda modułu Endpoint(String, Action<EndpointConfiguration>) ładującego, która może służyć do uzupełnienia ustawień skonfigurowanego punktu końcowego:

var builder = WebApplication.CreateBuilder(args);

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

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

KestrelServerOptions.ConfigurationLoader można uzyskać bezpośredni dostęp, aby kontynuować iterowanie istniejącego modułu ładującego, na przykład podane przez WebApplicationBuilder.WebHostusługę .

• Sekcja konfiguracji dla każdego punktu końcowego jest dostępna w opcjach w metodzie Endpoint , dzięki czemu ustawienia niestandardowe mogą być odczytywane.
• KestrelServerOptions.Configure(IConfiguration) może być wywoływana wiele razy, ale używana jest tylko ostatnia konfiguracja, chyba że Load jawnie wywoływana jest poprzednia konfiguracja. Domyślny host nie wywołuje metody Load , aby można było zamienić jego domyślną sekcję konfiguracji.
• KestrelConfigurationLoader Dubluje rodzinę Listen interfejsów API z KestrelServerOptions jako Endpoint przeciążeń, dzięki czemu punkty końcowe kodu i konfiguracji można skonfigurować w tym samym miejscu. Te przeciążenia nie używają nazw i używają tylko ustawień domyślnych z konfiguracji.

Konfigurowanie punktów końcowych w kodzie

KestrelServerOptions Udostępnia metody konfigurowania punktów końcowych w kodzie:

• Listen
• ListenLocalhost
• ListenAnyIP
• ListenUnixSocket
• ListenNamedPipe

Gdy oba Listen interfejsy API i UseUrls są używane jednocześnie, Listen punkty końcowe zastępują UseUrls punkty końcowe.

Wiązanie z gniazdem TCP

Metody Listen, ListenLocalhosti ListenAnyIP wiążą się z gniazdem 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");
    });
});

Powyższy przykład:

• Konfiguruje punkty końcowe nasłuchujące na porcie 5000 i 5001.
• Konfiguruje protokół HTTPS dla punktu końcowego przy użyciu UseHttps metody rozszerzenia w pliku ListenOptions. Aby uzyskać więcej informacji, zobacz Konfigurowanie protokołu HTTPS w kodzie.

W systemie Windows można utworzyć certyfikaty z podpisem własnym przy użyciu New-SelfSignedCertificate polecenia cmdlet programu PowerShell. Aby zapoznać się z nieobsługiwanym przykładem, zobacz UpdateIISExpressSSLForChrome.ps1.

W systemach macOS, Linux i Windows można tworzyć certyfikaty przy użyciu protokołu OpenSSL.

Wiązanie z gniazdem systemu Unix

Nasłuchiwanie w gniazdach systemu Unix z ListenUnixSocket ulepszoną wydajnością za pomocą serwera Nginx, jak pokazano w tym przykładzie:

var builder = WebApplication.CreateBuilder(args);

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

• W pliku konfiguracji Nginx ustaw server>proxy_pass>locationwpis na .http://unix:/tmp/{KESTREL SOCKET}:/; {KESTREL SOCKET} to nazwa gniazda podanego ListenUnixSocket (na przykład kestrel-test.sock w poprzednim przykładzie).
• Upewnij się, że gniazdo jest zapisywalne przez serwer Nginx (na przykład chmod go+w /tmp/kestrel-test.sock).

Konfigurowanie domyślnych ustawień punktu końcowego

ConfigureEndpointDefaults(Action<ListenOptions>) określa konfigurację uruchamianą dla każdego określonego punktu końcowego. Wywołanie ConfigureEndpointDefaults wiele razy zastępuje poprzednią konfigurację.

var builder = WebApplication.CreateBuilder(args);

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

Uwaga

Punkty końcowe utworzone przez wywołanie przed wywołaniem ConfigureEndpointDefaults Listen nie będą miały zastosowanych wartości domyślnych.

Powiązanie portu dynamicznego

Po określeniu Kestrel numeru 0 portu dynamicznie wiąże się z dostępnym portem. W poniższym przykładzie pokazano, jak określić, który port Kestrel jest powiązany w czasie wykonywania:

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

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

        // ...
    }
});

Dynamiczne powiązanie portu nie jest dostępne w niektórych sytuacjach:

• KestrelServerOptions.ListenLocalhost
• Powiązanie protokołu HTTP/1.1 lub HTTP/2 opartego na protokole TCP oraz protokołu HTTP/3 opartego na protokole QUIC.

Konfigurowanie protokołu HTTPS

Kestrel obsługuje zabezpieczanie punktów końcowych przy użyciu protokołu HTTPS. Dane wysyłane za pośrednictwem protokołu HTTPS są szyfrowane przy użyciu protokołu Transport Layer Security (TLS) w celu zwiększenia bezpieczeństwa przesyłanych danych między klientem a serwerem.

Protokół HTTPS wymaga certyfikatu TLS. Certyfikat TLS jest przechowywany na serwerze i Kestrel jest skonfigurowany do korzystania z niego. Aplikacja może używać certyfikatu deweloperskiego ASP.NET Core HTTPS w lokalnym środowisku programistycznym. Certyfikat dewelopera nie jest zainstalowany w środowiskach innych niż rozwój. W środowisku produkcyjnym certyfikat TLS musi być jawnie skonfigurowany. Należy podać co najmniej certyfikat domyślny.

Sposób konfigurowania protokołu HTTPS i certyfikatu TLS zależy od sposobu konfigurowania punktów końcowych:

• Jeśli prefiksy adresów URL lub określ porty są używane tylko do definiowania punktów końcowych, protokół HTTPS może być używany tylko wtedy, gdy w konfiguracji punktu końcowego HTTPS zostanie podany domyślny certyfikat. Certyfikat domyślny można skonfigurować przy użyciu jednej z następujących opcji:
• Konfigurowanie protokołu HTTPS w usłudze appsettings.json
• Konfigurowanie protokołu HTTPS w kodzie

Konfigurowanie protokołu HTTPS w usłudze appsettings.json

Domyślny schemat konfiguracji ustawień aplikacji HTTPS jest dostępny dla programu Kestrel. Skonfiguruj wiele punktów końcowych, w tym adresy URL i certyfikaty do użycia, z pliku na dysku lub z magazynu certyfikatów.

Każdy punkt końcowy HTTPS, który nie określa certyfikatu (HttpsDefaultCert w poniższym przykładzie) wraca do certyfikatu zdefiniowanego w ramach Certificates:Default programu lub certyfikatu programistycznego.

Poniższy przykład dotyczy elementu appsettings.json, ale można użyć dowolnego źródła konfiguracji:

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

Ostrzeżenie

W poprzednim przykładzie hasło certyfikatu jest przechowywane w postaci zwykłego tekstu w pliku appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych podczas programowania. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Dostawca konfiguracji usługi Azure Key Vault. Wpisy tajne programowania nie powinny być używane do produkcji ani testowania.

Uwagi dotyczące schematu

• Nazwy punktów końcowych są niewrażliwe na wielkość liter. Na przykład elementy HTTPS i Https są równoważne.
• Parametr Url jest wymagany dla każdego punktu końcowego. Format tego parametru jest taki sam jak parametr konfiguracji najwyższego poziomu Urls , z wyjątkiem tego, że jest ograniczony do pojedynczej wartości. Zobacz formaty adresów URL we wcześniejszej wersji tego artykułu.
• Te punkty końcowe zastępują te zdefiniowane w konfiguracji najwyższego poziomu Urls , a nie dodawane do nich. Punkty końcowe zdefiniowane w kodzie za pośrednictwem Listen są skumulowane z punktami końcowymi zdefiniowanymi w sekcji konfiguracji.
• Sekcja jest opcjonalna Certificate . Certificate Jeśli sekcja nie jest określona, używane są wartości domyślne zdefiniowane wCertificates:Default. Jeśli nie są dostępne żadne wartości domyślne, używany jest certyfikat dewelopera. Jeśli nie ma żadnych wartości domyślnych i certyfikat programowania nie jest obecny, serwer zgłasza wyjątek i nie można go uruchomić.
• Sekcja Certificate obsługuje wiele źródeł certyfikatów.
• Dowolna liczba punktów końcowych może być zdefiniowana w elemecie Configuration, o ile nie powodują konfliktów portów.

Źródła certyfikatów

Węzły certyfikatów można skonfigurować do ładowania certyfikatów z wielu źródeł:

• Path i Password do ładowania plików pfx .
• Pathi KeyPath do ładowania plików pem.crt/ i .key. Password
• Subject i Store do załadowania z magazynu certyfikatów.

Na przykład Certificates:Default certyfikat można określić jako:

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

Konfigurowanie certyfikatów klienta w programie appsettings.json

ClientCertificateMode służy do konfigurowania zachowania certyfikatu klienta.

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

Ostrzeżenie

W poprzednim przykładzie hasło certyfikatu jest przechowywane w postaci zwykłego tekstu w pliku appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych podczas programowania. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Dostawca konfiguracji usługi Azure Key Vault. Wpisy tajne programowania nie powinny być używane do produkcji ani testowania.

Wartość domyślna to ClientCertificateMode.NoCertificate, gdzie Kestrel nie żąda ani nie wymaga certyfikatu od klienta.

Aby uzyskać więcej informacji, zobacz Konfigurowanie uwierzytelniania certyfikatów w programie ASP.NET Core.

Konfigurowanie protokołów SSL/TLS w usłudze appsettings.json

Protokoły SSL to protokoły używane do szyfrowania i odszyfrowywania ruchu między dwoma elementami równorzędnymi, tradycyjnie klientem i serwerem.

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

Ostrzeżenie

W poprzednim przykładzie hasło certyfikatu jest przechowywane w postaci zwykłego tekstu w pliku appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych podczas programowania. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Dostawca konfiguracji usługi Azure Key Vault. Wpisy tajne programowania nie powinny być używane do produkcji ani testowania.

Wartość domyślna , SslProtocols.Nonepowoduje Kestrel użycie domyślnych ustawień systemu operacyjnego w celu wybrania najlepszego protokołu. Jeśli nie masz określonego powodu do wybrania protokołu, użyj wartości domyślnej.

Konfigurowanie protokołu HTTPS w kodzie

W przypadku korzystania z interfejsu Listen API UseHttps metoda rozszerzenia w systemie ListenOptions jest dostępna do skonfigurowania protokołu 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 to ścieżka i nazwa pliku certyfikatu względem katalogu zawierającego pliki zawartości aplikacji.
• password to hasło wymagane do uzyskania dostępu do danych certyfikatu X.509.
• configureOptions to element Action do skonfigurowania elementu HttpsConnectionAdapterOptions. Zwraca wartość ListenOptions.
• storeName to magazyn certyfikatów, z którego ma być ładowany certyfikat.
• subject to nazwa podmiotu certyfikatu.
• allowInvalid wskazuje, czy należy wziąć pod uwagę nieprawidłowe certyfikaty, takie jak certyfikaty z podpisem własnym.
• location to lokalizacja magazynu do załadowania certyfikatu.
• serverCertificate jest certyfikatem X.509.

Aby uzyskać pełną listę UseHttps przeciążeń, zobacz UseHttps.

Konfigurowanie certyfikatów klienta w kodzie

ClientCertificateMode Konfiguruje wymagania dotyczące certyfikatu klienta.

var builder = WebApplication.CreateBuilder(args);

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

Wartość domyślna to NoCertificate, gdzie Kestrel nie żąda ani nie wymaga certyfikatu od klienta.

Aby uzyskać więcej informacji, zobacz Konfigurowanie uwierzytelniania certyfikatów w programie ASP.NET Core.

Konfigurowanie wartości domyślnych protokołu HTTPS w kodzie

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) określa konfigurację Action do uruchomienia dla każdego punktu końcowego HTTPS. Wywołanie ConfigureHttpsDefaults wiele razy zastępuje poprzednie Action wystąpienia ostatnim Action określonym.

var builder = WebApplication.CreateBuilder(args);

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

Uwaga

Punkty końcowe utworzone przez wywołanie przed wywołaniem ConfigureHttpsDefaults Listen nie będą miały zastosowanych wartości domyślnych.

Konfigurowanie protokołów SSL/TLS w kodzie

Protokoły SSL to protokoły używane do szyfrowania i odszyfrowywania ruchu między dwoma elementami równorzędnymi, tradycyjnie klientem i serwerem.

var builder = WebApplication.CreateBuilder(args);

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

Konfigurowanie filtru zestawów szyfrowania TLS w kodzie

W systemie Linux CipherSuitesPolicy można używać do filtrowania uzgadniania protokołu TLS na podstawie połączenia:

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

Konfigurowanie wskazania nazwy serwera

Wskazanie nazwy serwera (SNI) może służyć do hostowania wielu domen na tym samym adresie IP i porcie. SNI może służyć do oszczędzania zasobów przez obsługę wielu lokacji z jednego serwera.

Aby funkcja SNI działała, klient wysyła nazwę hosta dla bezpiecznej sesji do serwera podczas uzgadniania protokołu TLS, aby serwer mógł dostarczyć prawidłowy certyfikat. Klient używa dostarczonego certyfikatu do zaszyfrowanej komunikacji z serwerem podczas bezpiecznej sesji, która następuje po uzgadnianiu protokołu TLS.

Wszystkie witryny internetowe muszą działać w tym samym Kestrel wystąpieniu. Kestrel nie obsługuje udostępniania adresu IP i portu między wieloma wystąpieniami bez zwrotnego serwera proxy.

SNI można skonfigurować na dwa sposoby:

• Skonfiguruj mapowanie między nazwami hostów i opcjami HTTPS w konfiguracji. Na przykład plik JSON w appsettings.json pliku.
• Utwórz punkt końcowy w kodzie i wybierz certyfikat przy użyciu nazwy hosta z wywołaniem zwrotnym ServerCertificateSelector .

Konfigurowanie sieci SNI w appsettings.json

Kestrel program obsługuje protokół SNI zdefiniowany w konfiguracji. Punkt końcowy można skonfigurować za pomocą obiektu zawierającego Sni mapowanie między nazwami hostów i opcjami HTTPS. Nazwa hosta połączenia jest zgodna z opcjami i są one używane dla tego połączenia.

Poniższa konfiguracja dodaje punkt końcowy o nazwie MySniEndpoint , który używa sieci SNI do wybierania opcji HTTPS na podstawie nazwy hosta:

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

Ostrzeżenie

W poprzednim przykładzie hasło certyfikatu jest przechowywane w postaci zwykłego tekstu w pliku appsettings.json. Token $CREDENTIAL_PLACEHOLDER$ jest używany jako symbol zastępczy hasła certyfikatu. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach deweloperskich, zobacz Ochrona wpisów tajnych podczas programowania. Aby bezpiecznie przechowywać hasła certyfikatów w środowiskach produkcyjnych, zobacz Dostawca konfiguracji usługi Azure Key Vault. Wpisy tajne programowania nie powinny być używane do produkcji ani testowania.

Opcje protokołu HTTPS, które można zastąpić za pomocą sieci SNI:

• CertificateKonfiguruje źródło certyfikatu.
• Protocols Konfiguruje dozwolone protokoły HTTP.
• SslProtocols Konfiguruje dozwolone protokoły SSL.
• ClientCertificateModeKonfiguruje wymagania dotyczące certyfikatu klienta.

Nazwa hosta obsługuje dopasowywanie symboli wieloznacznych:

• Dokładne dopasowanie. Na przykład a.example.org pasuje do a.example.orgelementu .
• Prefiks symbolu wieloznakowego. Jeśli istnieje wiele dopasowań symboli wieloznacznych, zostanie wybrany najdłuższy wzorzec. Na przykład *.example.org dopasowania b.example.org i c.example.org.
• Pełne symbole wieloznaczne. * dopasowuje wszystkie inne elementy, w tym klientów, którzy nie korzystają z sieci SNI i nie wysyłają nazwy hosta.

Dopasowana konfiguracja SNI jest stosowana do punktu końcowego dla połączenia, przesłaniając wartości w punkcie końcowym. Jeśli połączenie nie jest zgodne ze skonfigurowaną nazwą hosta SNI, połączenie zostanie odrzucone.

Konfigurowanie sieci SNI przy użyciu kodu

Kestrel obsługuje interfejs SNI z kilkoma interfejsami API wywołania zwrotnego:

• ServerCertificateSelector
• ServerOptionsSelectionCallback
• TlsHandshakeCallbackOptions

SNI z ServerCertificateSelector

Kestrel obsługuje funkcję SNI za pośrednictwem wywołania zwrotnego ServerCertificateSelector . Wywołanie zwrotne jest wywoływane raz na połączenie, aby umożliwić aplikacji sprawdzenie nazwy hosta i wybranie odpowiedniego certyfikatu:

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

Kestrel obsługuje dodatkową dynamiczną konfigurację protokołu TLS za pośrednictwem wywołania zwrotnego ServerOptionsSelectionCallback . Wywołanie zwrotne jest wywoływane raz na połączenie, aby umożliwić aplikacji sprawdzenie nazwy hosta i wybranie odpowiedniego certyfikatu i konfiguracji protokołu TLS. Domyślne certyfikaty i ConfigureHttpsDefaults nie są używane z tym wywołaniem zwrotnym.

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

Kestrel obsługuje dodatkową dynamiczną konfigurację protokołu TLS za pośrednictwem wywołania zwrotnego TlsHandshakeCallbackOptions.OnConnection . Wywołanie zwrotne jest wywoływane raz na połączenie, aby umożliwić aplikacji sprawdzenie nazwy hosta i wybranie odpowiedniego certyfikatu, konfiguracji protokołu TLS i innych opcji serwera. Domyślne certyfikaty i ConfigureHttpsDefaults nie są używane z tym wywołaniem zwrotnym.

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

Konfigurowanie protokołów HTTP

Kestrel obsługuje wszystkie powszechnie używane wersje PROTOKOŁU HTTP. Punkty końcowe można skonfigurować tak, aby obsługiwały różne wersje PROTOKOŁU HTTP przy użyciu wyliczenia HttpProtocols , które określa dostępne opcje wersji PROTOKOŁU HTTP.

Protokół TLS jest wymagany do obsługi więcej niż jednej wersji protokołu HTTP. Uzgadnianie negocjacji protokołu TLS w warstwie aplikacji (ALPN) służy do negocjowania protokołu połączenia między klientem a serwerem, gdy punkt końcowy obsługuje wiele protokołów.

HttpProtocols wartość	Dozwolony protokół połączenia
Http1	Tylko http/1.1. Może być używany z protokołem TLS lub bez tego protokołu.
Http2	Tylko HTTP/2. Może być używany bez protokołu TLS tylko wtedy, gdy klient obsługuje tryb wcześniejszej wiedzy.
Http3	Tylko http/3. Wymaga protokołu TLS. Może być konieczne skonfigurowanie klienta do używania tylko protokołu HTTP/3.
Http1AndHttp2	HTTP/1.1 i HTTP/2. Protokół HTTP/2 wymaga, aby klient wybrał protokół HTTP/2 w uzgadnianiu protokołu TLS Application-Layer Protocol (ALPN ). W przeciwnym razie połączenie jest domyślnie nawiązane z protokołem HTTP/1.1.
Http1AndHttp2AndHttp3	HTTP/1.1, HTTP/2 i HTTP/3. Pierwsze żądanie klienta zwykle używa protokołu HTTP/1.1 lub HTTP/2, a alt-svc nagłówek odpowiedzi monituje klienta o uaktualnienie do protokołu HTTP/3. Protokół HTTP/2 i HTTP/3 wymaga protokołu TLS; w przeciwnym razie połączenie jest domyślnie ustawione na HTTP/1.1.

Domyślną wartością protokołu dla punktu końcowego jest HttpProtocols.Http1AndHttp2.

Ograniczenia protokołu TLS dla protokołu HTTP/2:

• Protokół TLS w wersji 1.2 lub nowszej
• Ponowne negocjowanie jest wyłączone
• Kompresja wyłączona
• Minimalne rozmiary wymiany kluczy efemerycznych:
  • Krzywa eliptyczna Diffie-Hellman (ECDHE) [RFC4492]: minimum 224 bitów
  • Pole skończone Diffie-Hellman (DHE) [TLS12]: minimum 2048 bitów
• Zestaw szyfrowania nie jest zabroniony.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] z krzywą eliptyczną P-256 [FIPS186] jest domyślnie obsługiwana.

Konfigurowanie protokołów HTTP w appsettings.json

appsettings.json Poniższy przykład ustanawia protokół połączenia HTTP/1.1 dla określonego punktu końcowego:

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

W sekcji można skonfigurować Kestrel:EndpointDefaults protokół domyślny. appsettings.json Poniższy przykład ustanawia protokół HTTP/1.1 jako domyślny protokół połączenia dla wszystkich punktów końcowych:

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

Protokoły określone w kodzie zastępują wartości ustawione przez konfigurację.

Konfigurowanie protokołów HTTP w kodzie

ListenOptions.Protocols służy do określania protokołów z wyliczeniem HttpProtocols .

Poniższy przykład umożliwia skonfigurowanie punktu końcowego dla połączeń HTTP/1.1, HTTP/2 i HTTP/3 na porcie 8000. Połączenia są zabezpieczone przez protokół TLS przy użyciu dostarczonego certyfikatu:

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

Zobacz też

• Kestrel serwer internetowy w programie ASP.NET Core
• Konfigurowanie opcji serwera internetowego ASP.NET Core Kestrel