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

Ve výchozím nastavení ASP.NET Core vazby na:

• http://localhost:5000
• https://localhost:5001 (když je k dispozici místní certifikát pro vývoj)

Adresy URL můžete zadat pomocí:

• ASPNETCORE_URLS proměnná prostředí.
• --urls argument příkazového řádku.
• urls konfigurační klíč hostitele.
• UseUrls extension method.

Hodnota poskytovaná pomocí těchto přístupů může být jeden nebo více koncových bodů HTTP a HTTPS (HTTPS, pokud je k dispozici výchozí certifikát). Nakonfigurujte hodnotu jako seznam oddělený středníkem (například "Urls": "http://localhost:8000;http://localhost:8001" ).

Další informace o těchto přístupech najdete v tématu Adresy URL serveru a Konfigurace přepsání.

Vytvoří se certifikát pro vývoj:

• Když je nainstalovaná sada .NET SDK.
• Nástroj dev-certs slouží k vytvoření certifikátu.

Některé prohlížeče vyžadují udělení explicitního oprávnění k důvěřování místnímu vývojovému certifikátu.

Project šablony konfigurují aplikace tak, aby ve výchozím nastavení běží na HTTPS, a zahrnují přesměrování HTTPS a podporu HSTS.

Voláním Listen metody nebo můžete nakonfigurovat ListenUnixSocket KestrelServerOptions předpony adres URL a porty pro Kestrel .

UseUrls, argument příkazového řádku, konfigurační klíč hostitele a proměnná prostředí fungují také, ale mají omezení, která jsou uvedená dále v této části (pro konfiguraci koncového bodu HTTPS musí být k dispozici --urls urls výchozí ASPNETCORE_URLS certifikát).

KestrelServerOptions Konfigurace:

ConfigureEndpointDefaults(Action <ListenOptions> )

Určuje konfiguraci, která Action se má spustit pro každý zadaný koncový bod. Volání ConfigureEndpointDefaults vícekrát nahradí předchozí Action hodnoty za poslední Action zadané.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });
});

Configure(IConfiguration)

Umožňuje Kestrel načíst koncové body z IConfiguration . Konfigurace musí být vymezená konfiguračním oddílem pro Kestrel .

Přetížení Configure(IConfiguration, bool) lze použít k povolení opětovného načtení koncových bodů při změně zdroje konfigurace.

IHostBuilder.ConfigureWebHostDefaults ve Configure(context.Configuration.GetSection("Kestrel"), reloadOnChange: true) výchozím nastavení volá pro načtení konfigurace a povolení Kestrel opětovného načítání.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "Https": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      }
    }
  }
}

Pokud je konfigurace opětovného načtení povolená a signalizována změna, jsou podnikovány následující kroky:

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

Klienti připojující se k upravenému koncovému bodu se mohou během restartování koncového bodu odpojit nebo odmítnout.

ConfigureHttpsDefaults(Akce <HttpsConnectionAdapterOptions> )

Určuje konfiguraci, která Action se má spustit pro každý koncový bod HTTPS. Volání ConfigureHttpsDefaults vícekrát nahradí předchozí Action hodnoty za poslední Action zadané.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        // certificate is an X509Certificate2
        listenOptions.ServerCertificate = certificate;
    });
});

ListenOptions.UseHttps

Nakonfigurujte Kestrel pro použití HTTPS.

ListenOptions.UseHttps Rozšíření:

• UseHttps: Nakonfigurujte Kestrel použití protokolu HTTPS s výchozím certifikátem. Vyvolá výjimku, pokud není nakonfigurovaný žádný výchozí certifikát.
• UseHttps(string fileName)
• UseHttps(string fileName, string password)
• UseHttps(string fileName, string password, Action<HttpsConnectionAdapterOptions> configureOptions)
• UseHttps(StoreName storeName, string subject)
• UseHttps(StoreName storeName, string subject, bool allowInvalid)
• UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location)
• UseHttps(StoreName storeName, string subject, bool allowInvalid, StoreLocation location, Action<HttpsConnectionAdapterOptions> configureOptions)
• UseHttps(X509Certificate2 serverCertificate)
• UseHttps(X509Certificate2 serverCertificate, Action<HttpsConnectionAdapterOptions> configureOptions)
• UseHttps(Action<HttpsConnectionAdapterOptions> configureOptions)

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í 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, jestli se mají považovat za neplatné certifikáty, například 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.

V produkčním prostředí musí být https explicitně nakonfigurovaný. Musí být poskytnut minimálně výchozí certifikát.

Podporované konfigurace popsané dále:

• Žádná konfigurace
• Nahrazení výchozího certifikátu z konfigurace
• Změna výchozích hodnot v kódu

Žádná konfigurace

Kestrel naslouchá na http://localhost:5000 a https://localhost:5001 (pokud je k dispozici výchozí certifikát).

Nahrazení výchozího certifikátu z konfigurace

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

V následujícím appsettings.json příkladu:

• Nastavte AllowInvalid na , pokud chcete povolit použití neplatných certifikátů (například certifikátů true podepsaných svým držitelem).
• Jakýkoli koncový bod HTTPS, který nezadá certifikát (v následujícím příkladu), se vrátí zpět k certifikátu definovanému v souboru nebo HttpsDefaultCert Certificates:Default vývojovému certifikátu.

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://localhost:5000"
      },
      "HttpsInlineCertFile": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "<path to .pfx file>",
          "Password": "<certificate password>"
        }
      },
      "HttpsInlineCertAndKeyFile": {
        "Url": "https://localhost:5002",
        "Certificate": {
          "Path": "<path to .pem/.crt file>",
          "KeyPath": "<path to .key file>",
          "Password": "<certificate password>"
        }
      },
      "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": "<certificate password>"
      }
    }
  }
}

Poznámky ke schématu:

• V názvech koncových bodů se velká a malá písmena nelišují. Například a HTTPS Https jsou ekvivalentní.
• Parametr Url je vyžadován pro každý koncový bod. Formát tohoto parametru je stejný jako konfigurační parametr nejvyšší úrovně s tím rozdílem, že je Urls omezený na jednu hodnotu.
• Tyto koncové body nahrazují ty, které jsou definované v konfiguraci nejvyšší Urls úrovně, místo aby je přidávají. Koncové body definované v kódu prostřednictvím Listen jsou kumulativní s koncovými body definovanými v konfiguračním oddílu.
• Oddíl Certificate je volitelný. Pokud Certificate oddíl není zadaný, použije se výchozí hodnoty definované v Certificates:Default . Pokud nejsou k dispozici žádné výchozí hodnoty, použije se certifikát pro vývoj. Pokud neexistují žádné výchozí hodnoty a vývojový certifikát neexistuje, server vyvolá výjimku a nespustí se.
• Oddíl Certificate podporuje více zdrojů certifikátů.
• V konfiguraci může být definovaný libovolný počet koncových bodů, pokud nezpůsobí konflikty portů.

Zdroje certifikátů

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

• Patha Password pro načtení souborů .pfx.
• Patha KeyPath Password pro načtení souborů .pem / .crt a .key.
• Subject``Storea , které se načtou z úložiště certifikátů.

Certifikát můžete Certificates:Default zadat například takto:

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

ConfigurationLoader

options.Configure(context.Configuration.GetSection("{SECTION}")) vrací KestrelConfigurationLoader s metodou .Endpoint(string name, listenOptions => { }) , kterou je možné použít k doplnění nastavení nakonfigurovaného koncového bodu:

webBuilder.UseKestrel((context, serverOptions) =>
{
    serverOptions.Configure(context.Configuration.GetSection("Kestrel"))
        .Endpoint("HTTPS", listenOptions =>
        {
            listenOptions.HttpsOptions.SslProtocols = SslProtocols.Tls12;
        });
});

KestrelServerOptions.ConfigurationLoader je možné přímo přistupovat a pokračovat v iteraci stávajícího zavaděče, jako je například ten, který poskytuje CreateDefaultBuilder .

• Konfigurační oddíl pro jednotlivé koncové body je k dispozici u možností v metodě , aby bylo možné číst Endpoint vlastní nastavení.
• Více konfigurací se může načíst tak, že options.Configure(context.Configuration.GetSection("{SECTION}")) se znovu zavolá s jiným oddílem. Použije se pouze poslední konfigurace, pokud Load není explicitně volána pro předchozí instance. Metabalíček nevolá , takže je možné nahradit jeho výchozí konfigurační Load oddíl.
• KestrelConfigurationLoader zrcadlí rodinu rozhraní API z jako přetížení, takže koncové body kódu a konfigurace je možné nakonfigurovat Listen KestrelServerOptions na stejném Endpoint místě. Tato přetížení nevyužívají názvy a využívají pouze výchozí nastavení z konfigurace.

Změna výchozích hodnot v kódu

ConfigureEndpointDefaults a lze použít ke změně výchozích nastavení pro a , včetně přepsání výchozího ConfigureHttpsDefaults certifikátu zadaného v předchozím ListenOptions HttpsConnectionAdapterOptions scénáři. ConfigureEndpointDefaults Před ConfigureHttpsDefaults nakonfigurování koncových bodů by se měly volat a .

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ConfigureEndpointDefaults(listenOptions =>
    {
        // Configure endpoint defaults
    });

    serverOptions.ConfigureHttpsDefaults(listenOptions =>
    {
        listenOptions.SslProtocols = SslProtocols.Tls12;
    });
});

Konfigurace koncových bodů pomocí Indikace názvu serveru

Indikace názvu serveru (SNI) je možné použít k hostování více domén na stejné IP adrese a portu. Aby SNI fungovala, 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á certifikát pro šifrovanou komunikaci se serverem během zabezpečené relace, která následuje po metodě handshake protokolu TLS.

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

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

SNI s ServerCertificateSelector

Kestrel podporuje SNI prostřednictvím ServerCertificateSelector zpětného volání. Zpětné volání se vyvolá jednou pro připojení, aby aplikace mohla zkontrolovat název hostitele a vybrat příslušný certifikát. Následující kód zpětného volání lze použít ve volání metody souboru ConfigureWebHostDefaults Program.cs projektu:

//using System.Security.Cryptography.X509Certificates;
//using Microsoft.AspNetCore.Server.Kestrel.Https;

webBuilder.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 != null && certs.TryGetValue(name, out var cert))
                {
                    return cert;
                }

                return exampleCert;
            };
        });
    });
});

SNI s ServerOptionsSelectionCallback

Kestrel podporuje další dynamickou konfiguraci protokolu TLS prostřednictvím ServerOptionsSelectionCallback zpětného volání. Zpětné volání se vyvolá jednou pro 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 nejsou používány s tímto zpětným voláním.

//using System.Security.Cryptography.X509Certificates;
//using Microsoft.AspNetCore.Server.Kestrel.Https;

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

//using System.Security.Cryptography.X509Certificates;
//using Microsoft.AspNetCore.Server.Kestrel.Https;

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

SNI v konfiguraci

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

Následující konfigurace přidá koncový bod s názvem 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": "<certificate password>"
            }
          },
          "*": {
            // 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": "<certificate password>"
      }
    }
  }
}

Možnosti HTTPS, které lze přepsat pomocí SNI:

• Certificate nakonfiguruje zdroj certifikátu.
• Protocolsnakonfiguruje povolené protokoly HTTP.
• SslProtocolsnakonfiguruje povolené protokoly SSL.
• ClientCertificateModenakonfiguruje požadavky na klientský certifikát.

Název hostitele podporuje porovnávání se zástupnými znaky:

• Přesná shoda. Například odpovídá a.example.org a.example.org .
• Předpona se zástupným znakem. Pokud existuje více shod se zástupnými znaky, zvolí se nejdelší vzor. Například odpovídá *.example.org a b.example.org c.example.org .
• Úplný zástupný znak. * odpovídá všemu ostatnímu, včetně klientů, kteří nepou3/4í sni a neposílejí název hostitele.

Pro koncový bod pro připojení se použije odpovídající konfigurace SNI, která přepíše hodnoty v koncovém bodě. Pokud se připojení neshoduje s nakonfigurovaným názvem hostitele SNI, připojení se zamítne.

Požadavky na SNI

• Spuštění v cílovém rozhraní netcoreapp2.1 nebo novějším. V net461 systému nebo novějším je zpětné volání vyvoláno, ale name je vždy null . je také v případě, že klient při ověřování TLS handshake nezadá parametr názvu name null hostitele.
• Všechny weby běží na stejné Kestrel instanci. Kestrel nepodporuje sdílení IP adresy a portu mezi více instancemi bez reverzního proxy serveru.

Protokoly SSL/TLS

Protokoly SSL jsou protokoly, které se používají k šifrování a dešifrování provozu mezi dvěma partnerskými vztahy, tradičně klientem a serverem.

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

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

Výchozí hodnota způsobí, že použije výchozí nastavení operačního systému pro SslProtocols.None výběr Kestrel nejlepšího protokolu. Pokud nemáte konkrétní důvod pro výběr protokolu, použijte výchozí nastavení.

Klientské certifikáty

ClientCertificateModenakonfiguruje požadavky na klientský certifikát.

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

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

Výchozí hodnota je , ClientCertificateMode.NoCertificate kde nebude požadovat nebo Kestrel vyžadovat certifikát od klienta.

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

Protokolování připojení

Voláním UseConnectionLogging vysíláte protokoly na úrovni ladění pro komunikaci na úrovni byte u připojení. Protokolování připojení je užitečné při řešení potíží při komunikaci nízké úrovně, například během šifrování TLS a za nástroji prox. Pokud UseConnectionLogging je umístěný před , UseHttps šifrovaný provoz se zaprotokoluje. Pokud UseConnectionLogging se umístí za , UseHttps dešifrovaný provoz se zaprotokoluje. Jedná se o integrovaný middleware pro připojení.

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseConnectionLogging();
    });
});

Vytvoření vazby k soketu TCP

Metoda Listen se váže na soket TCP a možnost lambda povoluje konfiguraci certifikátu X.509:

public static void Main(string[] args)
{
    CreateHostBuilder(args).Build().Run();
}

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            webBuilder.ConfigureKestrel(serverOptions =>
            {
                serverOptions.Listen(IPAddress.Loopback, 5000);
                serverOptions.Listen(IPAddress.Loopback, 5001, 
                    listenOptions =>
                    {
                        listenOptions.UseHttps("testCert.pfx", 
                            "testPassword");
                    });
            })
            .UseStartup<Startup>();
        });

Příklad konfiguruje HTTPS pro koncový bod pomocí ListenOptions . Stejné rozhraní API použijte ke konfiguraci dalších Kestrel nastavení pro konkrétní koncové body.

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

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

Vytvoření vazby k unixovému soketu

Naslouchejte unixovému soketu a vylepšete výkon serveru ListenUnixSocket Nginx, jak je znázorněno v tomto příkladu:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock");
    serverOptions.ListenUnixSocket("/tmp/kestrel-test.sock", 
        listenOptions =>
        {
            listenOptions.UseHttps("testCert.pfx", 
                "testpassword");
        });
})

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

Port 0

Když je zadané číslo 0 portu, Kestrel dynamicky se sváže s dostupným portem. Následující příklad ukazuje, jak určit port vázaný Kestrel za běhu:

public void Configure(IApplicationBuilder app)
{
    var serverAddressesFeature = 
        app.ServerFeatures.Get<IServerAddressesFeature>();

    app.UseStaticFiles();

    app.Run(async (context) =>
    {
        context.Response.ContentType = "text/html";
        await context.Response
            .WriteAsync("<!DOCTYPE html><html lang=\"en\"><head>" +
                "<title></title></head><body><p>Hosted by Kestrel</p>");

        if (serverAddressesFeature != null)
        {
            await context.Response
                .WriteAsync("<p>Listening on the following addresses: " +
                    string.Join(", ", serverAddressesFeature.Addresses) +
                    "</p>");
        }

        await context.Response.WriteAsync("<p>Request URL: " +
            $"{context.Request.GetDisplayUrl()}<p>");
    });
}

Když je aplikace spuštěná, výstup okna konzoly indikuje dynamický port, na kterém je aplikace k dispozici:

Listening on the following addresses: http://127.0.0.1:48508

Omezení

Koncové body nakonfigurujte následujícími přístupy:

• UseUrls
• --urls Argument příkazového řádku
• urls konfigurační klíč hostitele
• ASPNETCORE_URLS proměnná prostředí

Tyto metody jsou užitečné pro práci kódu s jinými servery než Kestrel . Je však třeba mít na paměti následující omezení:

• HTTPS nelze s těmito přístupy použít, pokud není v konfiguraci koncového bodu HTTPS poskytnut výchozí certifikát (například pomocí konfigurace nebo konfiguračního souboru, jak je uvedeno výše KestrelServerOptions v tomto článku).
• Pokud se současně používají přístupy Listen i , koncové body UseUrls Listen přepíší UseUrls koncové body.

Konfigurace koncového bodu služby IIS

Při použití služby IIS jsou vazby adresy URL pro vazby přepsání služby IIS nastaveny buď pomocí Listen , nebo UseUrls . Další informace najdete v tématu ASP.NET Core Module.

ListenOptions.Protocols

Vlastnost vytváří protokoly HTTP ( ) povolené na koncovém bodu Protocols HttpProtocols připojení nebo pro server. Přiřaďte Protocols hodnotu vlastnosti z HttpProtocols výčtu.

Výchozí hodnota ListenOptions.Protocols pro každý koncový bod je HttpProtocols.Http1AndHttp2 .

Omezení PROTOKOLU TLS pro HTTP/2:

• TLS verze 1.2 nebo novější
• Zakázáno znovuschopné vyjednávání
• Komprese zakázaná
• Minimální velikosti dočasného výměny klíčů:
  • Diffie-Hellman eliptické křivky (ECDH) [ RFC4492 ] : 224 bity minima
  • Omezené pole Diffie-Hellman (DHE) [ TLS12 ] : 2048 bity minima
• Šifrovací sada není zakázaná.

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

Následující příklad povoluje připojení HTTP/1.1 a HTTP/2 na portu 8000. Připojení TLS zabezpečuje pomocí zadaného certifikátu:

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
    });
});

V systému Linux se CipherSuitesPolicy dá použít k filtrování ověřování TLS metodou handshake na základě jednotlivých připojení:

// using System.Net.Security;
// using Microsoft.AspNetCore.Hosting;
// using Microsoft.AspNetCore.Server.Kestrel.Core;
// using Microsoft.Extensions.DependencyInjection;
// using Microsoft.Extensions.Hosting;

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

Middleware připojení

Middleware vlastního připojení může v případě potřeby filtrovat handshake TLS na základě jednotlivých připojení pro konkrétní šifry.

Následující příklad vyvolá NotSupportedException jakýkoli šifrovací algoritmus, který aplikace nepodporuje. Případně můžete definovat a porovnat ITlsHandshakeFeature. CipherAlgorithm se seznamem přijatelných šifrovacích sad.

Pro šifrovací algoritmus CipherAlgorithmType. null se nepoužívá žádné šifrování.

// using System.Net;
// using Microsoft.AspNetCore.Connections;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.UseTlsFilter();
    });
});

using System;
using System.Security.Authentication;
using Microsoft.AspNetCore.Connections.Features;

namespace Microsoft.AspNetCore.Connections
{
    public static class TlsFilterConnectionMiddlewareExtensions
    {
        public static IConnectionBuilder UseTlsFilter(
            this IConnectionBuilder builder)
        {
            return builder.Use((connection, next) =>
            {
                var tlsFeature = connection.Features.Get<ITlsHandshakeFeature>();

                if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
                {
                    throw new NotSupportedException("Prohibited cipher: " +
                        tlsFeature.CipherAlgorithm);
                }

                return next();
            });
        }
    }
}

Filtrování připojení lze také nakonfigurovat prostřednictvím IConnectionBuilder lambda:

// using System;
// using System.Net;
// using System.Security.Authentication;
// using Microsoft.AspNetCore.Connections;
// using Microsoft.AspNetCore.Connections.Features;

webBuilder.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 8000, listenOptions =>
    {
        listenOptions.UseHttps("testCert.pfx", "testPassword");
        listenOptions.Use((context, next) =>
        {
            var tlsFeature = context.Features.Get<ITlsHandshakeFeature>();

            if (tlsFeature.CipherAlgorithm == CipherAlgorithmType.Null)
            {
                throw new NotSupportedException(
                    $"Prohibited cipher: {tlsFeature.CipherAlgorithm}");
            }

            return next();
        });
    });
});

Nastavení protokolu HTTP z konfigurace

CreateDefaultBuilder Při serverOptions.Configure(context.Configuration.GetSection("Kestrel")) načítání konfigurace volá ve výchozím nastavení Kestrel .

Následující appsettings.json příklad vytvoří HTTP/1.1 jako výchozí protokol připojení pro všechny koncové body:

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

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

Protokoly zadané v hodnotách přepisu kódu nastavených podle konfigurace

Předpony adresy URL

Při použití UseUrls , --urls argumentu příkazového řádku, urls konfiguračního klíče hostitele nebo ASPNETCORE_URLS proměnné prostředí můžou být předpony adresy URL v některém z následujících formátů.

Platné jsou pouze předpony adresy URL protokolu HTTP. Kestrel Při konfiguraci vazeb URL pomocí nepodporuje HTTPS UseUrls .

• Adresa IPv4 s číslem portu

  http://65.55.39.10:80/
  

  0.0.0.0 je zvláštní případ, který se váže ke všem adresám IPv4.

• Adresa IPv6 s číslem portu

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

  [::] je ekvivalentem protokolu IPv4 pro protokol IPv6 0.0.0.0 .

• Název hostitele s číslem portu

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

  Názvy hostitelů, * a + nejsou speciální. Cokoli se nerozpoznalo jako platná IP adresa nebo localhost se váže ke všem IP adresám IPv4 a IPv6. pokud chcete navazovat různé názvy hostitelů na různé ASP.NET Core aplikace na stejném portu, použijte HTTP.sys nebo reverzní proxy server. Mezi příklady zpětného proxy server patří IIS, Nginx nebo Apache.

  Upozornění

  Hostování v konfiguraci reverzního proxy serveru vyžaduje filtrování hostitele.

• localhostNázev 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/
  

  Při localhost zadání se Kestrel pokusí vytvořit propojení s rozhraními zpětné smyčky IPv4 i IPv6. Pokud je požadovaný port používán jinou službou na rozhraní zpětné smyčky, Kestrel spuštění se nespustí. Pokud je rozhraní zpětné smyčky v žádném jiném případě nedostupné (většinou vzhledem k tomu, že protokol IPv6 není podporovaný), Kestrel zaznamená upozornění.