Configurar endpoints para o servidor web ASP.NET Core Kestrel

Kestrel endereços fornecem a infraestrutura para ouvir as solicitações de entrada e encaminhá-las para o middleware apropriado. A combinação de um endereço e um protocolo define um ponto de extremidade.

• O endereço especifica a interface de rede na qual o servidor escuta as solicitações de entrada, como uma porta TCP.
• O protocolo especifica a comunicação entre o cliente e o servidor, como HTTP/1.1, HTTP/2 ou HTTP/3.
• Um endpoint pode ser protegido usando o esquema de URL https ou o método UseHttps.

Os endpoints podem ser configurados usando URLs, JSON em appsettings.jsone código. Este artigo descreve como usar cada opção para configurar um ponto de extremidade:

• Configurar pontos de extremidade
• Configurar HTTPS
• Configurar protocolos HTTP

Ponto de extremidade padrão

Novos projetos ASP.NET Core são configurados para se vincular a uma porta HTTP aleatória entre 5000-5300 e uma porta HTTPS aleatória entre 7000-7300. As portas selecionadas são armazenadas no arquivo de Properties/launchSettings.json gerado e podem ser modificadas pelo desenvolvedor. O ficheiro launchSetting.json só é utilizado no desenvolvimento local.

Se não houver nenhuma configuração de ponto de extremidade, Kestrel liga-se a http://localhost:5000.

Configurar pontos de extremidade

Kestrel pontos de extremidade monitoram conexões de entrada. Quando um endpoint é criado, ele deve ser configurado com o endereço que ouvirá. Normalmente, este é um endereço TCP e número de porta.

Existem várias opções para configurar terminais:

• Configurar endereços de terminal com URLs
• Especificar portas apenas
• Configurar pontos de extremidade no appsettings.json
• Configurar endpoints no código

Configurar pontos de extremidade com URLs

As seções a seguir explicam como configurar endpoints usando:

• ASPNETCORE_URLS variável de ambiente.
• --urls argumento de linha de comando.
• urls chave de configuração do host.
• UseUrls método de extensão.
• WebApplication.Urls propriedade.

Formatos de URL

Os URLs indicam os endereços IP ou host com portas e protocolos que o servidor deve escutar. A porta pode ser omitida se for o padrão para o protocolo (normalmente 80 e 443). Os URLs podem estar em qualquer um dos seguintes formatos.

• Endereço IPv4 com número de porta

  http://65.55.39.10:80/
  

  0.0.0.0 é um caso especial que se liga a todos os endereços IPv4.

• Endereço IPv6 com número de porta

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

  [::] é o equivalente IPv6 do IPv4 0.0.0.0.

• Wildcard host com número de porta

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

  Qualquer item não reconhecido como um endereço IP válido ou localhost é tratado como um wildcard que se liga a todos os endereços IPv4 e IPv6. Algumas pessoas gostam de usar * ou + para ser mais explícito. Para vincular nomes de host diferentes a aplicativos ASP.NET Core diferentes na mesma porta, use HTTP.sys ou um servidor proxy reverso.

  Exemplos de servidor proxy reverso incluem IIS, YARP, Nginx e Apache.

• Nome do host localhost com número de porta ou IP de loopback com número de porta

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

  Quando localhost é especificado, Kestrel tenta ligar-se às interfaces de loopback do IPv4 e do IPv6. Se a porta solicitada estiver em uso por outro serviço em qualquer interface de loopback, Kestrel falha ao iniciar. Se qualquer interface de loopback estiver indisponível por qualquer outro motivo (mais comumente porque o IPv6 não é suportado), Kestrel registrará um aviso.

Vários prefixos de URL podem ser especificados usando um delimitador de ponto-e-vírgula (;):

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

Para obter mais informações, consulte Configuração de substituição.

Prefixos de URL HTTPS

Os prefixos de URL HTTPS podem ser usados para definir pontos de extremidade somente se um certificado padrão for fornecido na configuração do ponto de extremidade HTTPS. Por exemplo, use a configuração KestrelServerOptions ou um arquivo de configuração, conforme mostrado mais à frente neste artigo.

Para mais informações, consulte como configurar o HTTPS em .

Especificar apenas portas

Aplicativos e contêineres geralmente recebem apenas uma porta para escutar, como a porta 80, sem restrições adicionais, como host ou caminho. HTTP_PORTS e HTTPS_PORTS são chaves de configuração que especificam as portas de escuta para os servidores Kestrel e HTTP.sys. Essas chaves podem ser especificadas como variáveis de ambiente definidas com os prefixos DOTNET_ ou ASPNETCORE_, ou especificadas diretamente por meio de qualquer outra entrada de configuração, como appsettings.json. Cada um é uma lista delimitada por ponto-e-vírgula de valores de porta, conforme mostrado no exemplo a seguir:

ASPNETCORE_HTTP_PORTS=80;8080
ASPNETCORE_HTTPS_PORTS=443;8081

O exemplo anterior é uma abreviação para a configuração a seguir, que especifica o esquema (HTTP ou HTTPS) e qualquer host ou IP.

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

As chaves de configuração HTTP_PORTS e HTTPS_PORTS são de prioridade mais baixa e são substituídas por URLs ou valores fornecidos diretamente no código. Os certificados ainda precisam ser configurados separadamente por meio de mecânicas específicas do servidor para HTTPS.

Configurar pontos de extremidade em appsettings.json

Kestrel pode carregar endpoints a partir de uma instância IConfiguration. Por padrão, a configuração Kestrel é carregada a partir da secção Kestrel e os endpoints são configurados em Kestrel:Endpoints.

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

O exemplo anterior:

• Usa appsettings.json como a fonte de configuração. No entanto, qualquer fonte IConfiguration pode ser usada.
• Adiciona um endpoint chamado MyHttpEndpoint na porta 8080.

Para obter mais informações sobre a configuração de endpoints com JSON, consulte as secções seguintes deste artigo que abordam a configuração de HTTPS e a configuração de protocolos HTTP no appsettings.json.

Atualizar endpoints a partir da configuração

A recarga da configuração do ponto de extremidade quando a fonte de configuração é alterada está ativada por padrão. Ele pode ser desativado usando KestrelServerOptions.Configure(IConfiguration, Boolean).

Se for sinalizada uma alteração, são tomadas as seguintes medidas:

• A nova configuração é comparada à antiga, e qualquer ponto de extremidade sem alterações na configuração não é modificado.
• Os pontos de extremidade removidos ou modificados recebem 5 segundos para concluir as solicitações de processamento e desligar.
• Novos ou modificados pontos finais são iniciados.

Os clientes que se conectam a um ponto de extremidade modificado podem ser desconectados ou recusados enquanto o ponto de extremidade é reiniciado.

Carregador de Configuração

KestrelServerOptions.Configure retorna um KestrelConfigurationLoader. O método Endpoint(String, Action<EndpointConfiguration>) do carregador pode ser usado para complementar as definições de um endpoint configurado.

var builder = WebApplication.CreateBuilder(args);

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

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

KestrelServerOptions.ConfigurationLoader pode ser acessado diretamente para continuar iterando no carregador existente, como o fornecido pelo WebApplicationBuilder.WebHost.

• A seção de configuração para cada ponto de extremidade está disponível nas opções no método Endpoint para que as configurações personalizadas possam ser lidas.
• KestrelServerOptions.Configure(IConfiguration) pode ser chamado várias vezes, mas apenas a última configuração é usada, a menos que Load seja explicitamente chamada em instâncias anteriores. O host padrão não chama Load para que sua seção de configuração padrão possa ser substituída.
• KestrelConfigurationLoader espelha a família Listen de APIs do KestrelServerOptions à medida que Endpoint sobrecarrega, para que o código e os pontos de extremidade de configuração possam ser configurados no mesmo local. Essas sobrecargas não usam nomes e utilizam apenas as definições padrão da configuração.

Configurar pontos de extremidade no código

KestrelServerOptions fornece métodos para configurar pontos de extremidade no código:

• Listen
• ListenLocalhost
• ListenAnyIP
• ListenUnixSocket
• ListenNamedPipe

Quando ambas as APIs UseUrls , Listen e são usadas simultaneamente, os endpoints Listen têm prioridade sobre os endpoints UseUrls.

Ligar a um soquete TCP

Os métodos Listen, ListenLocalhoste ListenAnyIP ligam-se a um soquete 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");
    });
});

O exemplo anterior:

• Configura pontos de extremidade que escutam nas portas 5000 e 5001.
• Configura HTTPS para um endpoint com o método de extensão UseHttps em ListenOptions. Para obter mais informações, consulte Configurar HTTPS no código.

No Windows, certificados autoassinados podem ser criados usando o cmdlet New-SelfSignedCertificate PowerShell. Para obter um exemplo sem suporte, consulte UpdateIISExpressSSLForChrome.ps1.

No macOS, Linux e Windows, os certificados podem ser criados usando OpenSSL.

Vincular a um soquete Unix

Utilize um socket Unix com ListenUnixSocket para melhorar o desempenho com o Nginx, como demonstrado neste exemplo:

var builder = WebApplication.CreateBuilder(args);

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

• No arquivo de configuração do Nginx, defina a entrada server>location>proxy_pass como http://unix:/tmp/{KESTREL SOCKET}:/;. {KESTREL SOCKET} é o nome do soquete fornecido ao ListenUnixSocket (por exemplo, kestrel-test.sock no exemplo anterior).
• Certifique-se de que o soquete é gravável por Nginx (por exemplo, chmod go+w /tmp/kestrel-test.sock).

Configurar padrões de ponto final

ConfigureEndpointDefaults(Action<ListenOptions>) especifica a configuração que é executada para cada ponto de extremidade especificado. Chamar ConfigureEndpointDefaults várias vezes substitui a configuração anterior.

var builder = WebApplication.CreateBuilder(args);

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

Observação

Os pontos de extremidade criados ao chamar Listenantes de chamar ConfigureEndpointDefaults não terão os padrões aplicados.

Ligação dinâmica de portas

Quando o número da porta 0 é especificado, Kestrel se liga dinamicamente a uma porta disponível. O exemplo a seguir mostra como determinar a qual porta Kestrel foi atribuída durante a execução:

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

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

        // ...
    }
});

A vinculação dinâmica de uma porta não está disponível em algumas situações:

• KestrelServerOptions.ListenLocalhost
• Vinculando HTTP/1.1 ou HTTP/2 baseado em TCP e HTTP/3 baseado em QUIC.

Configurar HTTPS

Kestrel suporta a proteção de endpoints com HTTPS. Os dados enviados por HTTPS são criptografados usando Transport Layer Security (TLS) para aumentar a segurança dos dados transferidos entre o cliente e o servidor.

HTTPS requer um certificado TLS. O certificado TLS é armazenado no servidor e Kestrel está configurado para usá-lo. Um aplicativo pode usar o certificado de desenvolvimento ASP.NET Core HTTPS em um ambiente de desenvolvimento local. O certificado de desenvolvimento não é instalado em ambientes que não sejam de desenvolvimento. Na produção, um certificado TLS deve ser explicitamente configurado. No mínimo, um certificado padrão deve ser fornecido.

A maneira como o HTTPS e o certificado TLS são configurados depende de como os pontos de extremidade são configurados:

• Se prefixos de URL ou especificar portas somente são usadas para definir pontos de extremidade, HTTPS pode ser usado somente se um certificado padrão for fornecido na configuração de ponto de extremidade HTTPS. Um certificado padrão pode ser configurado com uma das seguintes opções:
• Configurar HTTPS em appsettings.json
• Configurar HTTPS no código

Configurar HTTPS no appsettings.json

Um esquema de configuração padrão para aplicações HTTPS está disponível para Kestrel. Configure vários endpoints, incluindo os URLs e os certificados a serem usados, a partir de um ficheiro no disco ou de uma loja de certificados.

Qualquer ponto de extremidade HTTPS que não especifique um certificado (HttpsDefaultCert no exemplo a seguir) retornará ao certificado definido em Certificates:Default ou ao certificado de desenvolvimento.

O exemplo a seguir é para appsettings.json, mas qualquer fonte de configuração pode ser usada:

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

Advertência

No exemplo anterior, a senha do certificado é armazenada em texto sem formatação no appsettings.json. O token $CREDENTIAL_PLACEHOLDER$ é usado como um espaço reservado para a senha do certificado. Para armazenar senhas de certificado com segurança em ambientes de desenvolvimento, veja Proteção de segredos no desenvolvimento. Para que as senhas de certificado sejam armazenadas com segurança em ambientes de produção, consulte provedor de configuração do Azure Key Vault. Os segredos de desenvolvimento não devem ser usados para produção ou teste.

Notas de esquema

• Os nomes dos endpoints não distinguem maiúsculas de minúsculas. Por exemplo, HTTPS e Https são equivalentes.
• O parâmetro Url é necessário para cada ponto de extremidade. O formato para esse parâmetro é o mesmo que o parâmetro de configuração de Urls de nível superior, exceto que ele é limitado a um único valor. Veja os formatos de URL mencionados anteriormente neste artigo.
• Estes endpoints substituem os definidos na configuração de Urls de nível superior, em vez de acrescentá-los. Os pontos de extremidade definidos no código via Listen são cumulativos com os pontos de extremidade definidos na seção de configuração.
• A secção Certificate é opcional. Se a seção Certificate não for especificada, os padrões definidos em Certificates:Default serão usados. Se nenhum padrão estiver disponível, o certificado de desenvolvimento será usado. Se não houver padrões e o certificado de desenvolvimento não estiver presente, o servidor lançará uma exceção e falhará ao iniciar.
• A seção Certificate oferece suporte a várias fontes de certificado.
• Qualquer número de endpoints pode ser definido em Configuration, desde que não cause conflitos de porta.

Fontes de certificados

Os nós de certificado podem ser configurados para carregar certificados de várias fontes:

• Path e Password para carregar arquivos .pfx.
• Path, KeyPath e Password para carregar os arquivos .pem,/.crt, e .key.
• Subject e Store para carregar a partir do armazenamento de certificados.

Por exemplo, o certificado Certificates:Default pode ser especificado como:

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

Configurar certificados de cliente no appsettings.json

ClientCertificateMode é utilizado para configurar o comportamento dos certificados de cliente.

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

Advertência

No exemplo anterior, a senha do certificado é armazenada em texto sem formatação no appsettings.json. O token $CREDENTIAL_PLACEHOLDER$ é usado como um espaço reservado para a senha do certificado. Para armazenar senhas de certificado com segurança em ambientes de desenvolvimento, veja Proteção de segredos no desenvolvimento. Para que as senhas de certificado sejam armazenadas com segurança em ambientes de produção, consulte provedor de configuração do Azure Key Vault. Os segredos de desenvolvimento não devem ser usados para produção ou teste.

O valor padrão é ClientCertificateMode.NoCertificate, onde Kestrel não solicita ou exige um certificado do cliente.

Para obter mais informações, consulte Configurar autenticação de certificado no ASP.NET Core.

Configurar protocolos SSL/TLS no appsettings.json

Os protocolos SSL são protocolos usados para criptografar e descriptografar o tráfego entre dois pares, tradicionalmente um cliente e um servidor.

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

Advertência

No exemplo anterior, a senha do certificado é armazenada em texto sem formatação no appsettings.json. O token $CREDENTIAL_PLACEHOLDER$ é usado como um espaço reservado para a senha do certificado. Para armazenar senhas de certificado com segurança em ambientes de desenvolvimento, veja Proteção de segredos no desenvolvimento. Para que as senhas de certificado sejam armazenadas com segurança em ambientes de produção, consulte provedor de configuração do Azure Key Vault. Os segredos de desenvolvimento não devem ser usados para produção ou teste.

O valor padrão, SslProtocols.None, faz com que Kestrel use os padrões do sistema operacional para escolher o melhor protocolo. A menos que você tenha um motivo específico para selecionar um protocolo, use o padrão.

Configurar HTTPS no código

Ao usar a API Listen, o método de extensão UseHttps no ListenOptions está disponível para configurar 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 parâmetros:

• filename é o caminho e o nome de arquivo de um arquivo de certificado, relativo ao diretório que contém os arquivos de conteúdo do aplicativo.
• password é a senha necessária para acessar os dados do certificado X.509.
• configureOptions é um Action para configurar o HttpsConnectionAdapterOptions. Devolve o ListenOptions.
• storeName é o armazenamento de certificados a partir do qual carregar o certificado.
• subject é o nome do assunto do certificado.
• allowInvalid indica se certificados inválidos devem ser considerados, como certificados autoassinados.
• location é o local de armazenamento a partir do qual carregar o certificado.
• serverCertificate é o certificado X.509.

Para consultar uma lista completa de sobrecargas de UseHttps, veja UseHttps.

Configurar certificados de cliente no código

ClientCertificateMode configura os requisitos de certificado do cliente.

var builder = WebApplication.CreateBuilder(args);

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

O valor padrão é NoCertificate, onde Kestrel não solicita ou exige um certificado do cliente.

Para obter mais informações, consulte Configurar autenticação de certificado no ASP.NET Core.

Configurar padrões HTTPS no código

ConfigureHttpsDefaults(Action<HttpsConnectionAdapterOptions>) especifica uma configuração Action para ser executada para cada ponto de extremidade HTTPS. Chamar ConfigureHttpsDefaults múltiplas vezes substitui instâncias anteriores Action pela última instância de Action especificada.

var builder = WebApplication.CreateBuilder(args);

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

Observação

Os pontos de extremidade criados ao chamar Listenantes de chamar ConfigureHttpsDefaults não terão os padrões aplicados.

Configurar protocolos SSL/TLS no código

Os protocolos SSL são protocolos usados para criptografar e descriptografar o tráfego entre dois pares, tradicionalmente um cliente e um servidor.

var builder = WebApplication.CreateBuilder(args);

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

Configurar o filtro de pacotes de codificação TLS no código

No Linux, CipherSuitesPolicy pode ser usado para filtrar handshakes TLS por conexão:

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

Configurar indicação de nome do servidor

Indicação de Nome de Servidor (SNI) pode ser usada para hospedar vários domínios no mesmo endereço IP e porta. O SNI pode ser usado para conservar recursos servindo vários sites a partir de um servidor.

Para que o SNI funcione, o cliente envia o nome do host para a sessão segura para o servidor durante o handshake TLS para que o servidor possa fornecer o certificado correto. O cliente usa o certificado fornecido para comunicação criptografada com o servidor durante a sessão segura que segue o handshake TLS.

Todos os websites devem ser executados na instância Kestrel. Kestrel não suporta a partilha de endereço IP e porta entre várias instâncias sem um proxy reverso.

O SNI pode ser configurado de duas maneiras:

• Configure um mapeamento entre nomes de host e opções HTTPS no Configuration. Por exemplo, JSON no arquivo appsettings.json.
• Crie um ponto de extremidade no código e selecione um certificado usando o nome do host com o callback ServerCertificateSelector.

Configurar o SNI no appsettings.json

Kestrel suporta SNI definido na configuração. Um ponto de extremidade pode ser configurado com um objeto Sni que contém um mapeamento entre nomes de host e opções HTTPS. O nome do host de conexão corresponde às opções e elas são usadas para essa conexão.

A configuração a seguir adiciona um ponto de extremidade chamado MySniEndpoint que usa SNI para selecionar opções HTTPS com base no nome do host:

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

Advertência

No exemplo anterior, a senha do certificado é armazenada em texto sem formatação no appsettings.json. O token $CREDENTIAL_PLACEHOLDER$ é usado como um espaço reservado para a senha do certificado. Para armazenar senhas de certificado com segurança em ambientes de desenvolvimento, veja Proteção de segredos no desenvolvimento. Para que as senhas de certificado sejam armazenadas com segurança em ambientes de produção, consulte provedor de configuração do Azure Key Vault. Os segredos de desenvolvimento não devem ser usados para produção ou teste.

Opções HTTPS que podem ser substituídas pelo SNI:

• Certificate configura a origem do certificado .
• Protocols configura os protocolos HTTP permitidos.
• SslProtocols configura os protocolos permitidos de SSL .
• ClientCertificateMode configura os requisitos de certificado de cliente .

O nome do host oferece suporte à correspondência por caracteres substitutos:

• Correspondência exata. Por exemplo, a.example.org corresponde a.example.org.
• Prefixo de substituição. Se houver várias correspondências curinga, o padrão mais longo será escolhido. Por exemplo, *.example.org corresponde a b.example.org e c.example.org.
• Curinga completo. * corresponde a todo o resto, incluindo clientes que não estão usando SNI e não enviam um nome de host.

A configuração SNI correspondente é aplicada ao ponto final da conexão, substituindo os valores no ponto final. Se uma conexão não corresponder a um nome de host SNI configurado, a conexão será recusada.

Configurar SNI com código

Kestrel suporta SNI com várias APIs de 'callback':

• ServerCertificateSelector
• ServerOptionsSelectionCallback
• TlsHandshakeCallbackOptions

SNI com ServerCertificateSelector

Kestrel suporta SNI através do callback ServerCertificateSelector. O callback é invocado uma vez por conexão para permitir que a aplicação inspecione o nome do host e selecione o certificado apropriado.

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

Kestrel suporta configuração TLS dinâmica adicional através do retorno de chamada ServerOptionsSelectionCallback. O retorno de chamada é invocado uma vez por conexão para permitir que o aplicativo inspecione o nome do host e selecione o certificado apropriado e a configuração TLS. Os certificados padrão e o ConfigureHttpsDefaults não são usados com este retorno de chamada.

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

Kestrel suporta configuração TLS dinâmica adicional através do retorno de chamada TlsHandshakeCallbackOptions.OnConnection. O retorno de chamada é invocado uma vez por conexão para permitir que o aplicativo inspecione o nome do host e selecione o certificado apropriado, a configuração TLS e outras opções do servidor. Os certificados padrão e o ConfigureHttpsDefaults não são usados com este retorno de chamada.

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

Configurar protocolos HTTP

Kestrel suporta todas as versões HTTP comumente usadas. Os pontos de extremidade podem ser configurados para suportar diferentes versões HTTP usando o enum HttpProtocols, que especifica as opções de versão HTTP disponíveis.

O TLS é necessário para suportar mais de uma versão HTTP. O handshake TLS Application-Layer Protocol Negotiation (ALPN) é usado para negociar o protocolo de conexão entre o cliente e o servidor quando um ponto de acesso suporta múltiplos protocolos.

Valor HttpProtocols	Protocolo de conexão permitido
Http1	HTTP/1.1 apenas. Pode ser usado com ou sem TLS.
Http2	HTTP/2 apenas. Pode ser usado sem TLS somente se o cliente suportar um modo Conhecimento Prévio.
Http3	HTTP/3 apenas. Requer o TLS. O cliente pode precisar ser configurado para usar somente HTTP/3.
Http1AndHttp2	HTTP/1.1 e HTTP/2. HTTP/2 requer que o cliente selecione HTTP/2 no TLS Application-Layer Protocol Negotiation (ALPN) handshake; caso contrário, o padrão de conexão é HTTP/1.1.
Http1AndHttp2AndHttp3	HTTP/1.1, HTTP/2 e HTTP/3. A primeira solicitação de cliente normalmente usa HTTP/1.1 ou HTTP/2, e o cabeçalho de resposta alt-svc solicita que o cliente atualize para HTTP/3. HTTP/2 e HTTP/3 requer TLS; caso contrário, o padrão de conexão é HTTP/1.1.

O valor de protocolo padrão para um endpoint é HttpProtocols.Http1AndHttp2.

Restrições TLS para HTTP/2:

• TLS versão 1.2 ou posterior
• Renegociação desativada
• Compressão desativada
• Tamanhos mínimos de troca de chaves efêmeras:
  • Curva elíptica Diffie-Hellman (ECDHE) [RFC4492]: mínimo de 224 bits
  • Diffie-Hellman de campo finito (DHE) [TLS12]: mínimo de 2048 bits
• Cipher suite não proibida.

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 [TLS-ECDHE] com a curva elíptica P-256 [FIPS186] é suportada por padrão.

Configurar protocolos HTTP no appsettings.json

O exemplo de appsettings.json a seguir estabelece o protocolo de conexão HTTP/1.1 para um ponto de extremidade específico:

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

Um protocolo padrão pode ser configurado na seção Kestrel:EndpointDefaults. O exemplo appsettings.json a seguir estabelece HTTP/1.1 como o protocolo de conexão padrão para todos os endereços.

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

Os protocolos especificados no código substituem os valores definidos pela configuração.

Configurar protocolos HTTP no código

ListenOptions.Protocols é usado para especificar protocolos com o HttpProtocols enum.

O exemplo a seguir configura um ponto de extremidade para conexões HTTP/1.1, HTTP/2 e HTTP/3 na porta 8000. As conexões são protegidas por TLS com um certificado fornecido:

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

Personalizar pontos finais de pipes nomeados Kestrel

O suporte de tubo nomeado do Kestrelinclui opções avançadas de personalização. A propriedade CreateNamedPipeServerStream nas opções de pipe nomeado permite que os pipes sejam personalizados por ponto de extremidade.

Isso é útil, por exemplo, num aplicativo Kestrel que requer dois pontos terminais com diferentes níveis de segurança de acesso . A opção CreateNamedPipeServerStream pode ser usada para criar pipes com configurações de segurança personalizadas, dependendo do nome do pipe.

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

var builder = WebApplication.CreateBuilder();

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

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

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

var app = builder.Build();

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

app.Run();

Ver também

• Kestrel servidor web no ASP.NET Core
• Configurar opções para o servidor Web ASP.NET Core Kestrel