Impor o uso de HTTPS no ASP.NET Core

Projetos de API

Os projetos que usam APIs Web devem:

• Não escutar em HTTP.
• Fechar a conexão com o código de status 400 (Solicitação Inválida) e não atender à solicitação.

Para desabilitar o redirecionamento de HTTP em uma API, defina a ASPNETCORE_URLS variável de ambiente ou use o sinalizador de linha de comando --urls. Para obter mais informações, consulte Ambientes de tempo de execução do ASP.NET Core e 8 maneiras de definir as URLs para um aplicativo ASP.NET Core de Andrew Lock.

HSTS e projetos de API

A abordagem segura para HTTP Strict Transport Security Protocol (HSTS) é configurar projetos de API para aceitar e responder apenas por HTTPS.

Redirecionamento de HTTP para HTTPS (ERR_INVALID_REDIRECT na solicitação de preflight do CORS)

Quando uma solicitação para um endpoint usando HTTP é redirecionada para HTTPS com o método UseHttpsRedirection, o redirecionamento falha com o erro ERR_INVALID_REDIRECT na requisição preflight do CORS.

Os projetos de API podem rejeitar solicitações HTTP em vez de usar o UseHttpsRedirection método para redirecionar solicitações para HTTPS.

Exigir HTTPS

Para aplicativos Web ASP.NET Core de produção, a seguinte abordagem é recomendada:

• Para redirecionar solicitações HTTP para HTTPS, use o Middleware de Redirecionamento HTTPS (UseHttpsRedirection).

• Para enviar cabeçalhos HSTS para clientes, use o Middleware HSTS por meio do método UseHsts .

UseHttpsRedirection

O código a seguir chama o UseHttpsRedirection método no arquivo Program.cs :

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

O código destacado anterior:

• Usa a propriedade padrão HttpsRedirectionOptions.RedirectStatusCode com o código Status307TemporaryRedirect.
• Usa a propriedade padrão HttpsRedirectionOptions.HttpsPort (passando nulo), a menos que seja substituída pela variável de ASPNETCORE_HTTPS_PORT ambiente ou IServerAddressesFeature.

A abordagem recomendada é usar redirecionamentos temporários em vez de redirecionamentos permanentes. O cache de link pode causar um comportamento instável em ambientes de desenvolvimento. Se você preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente diferenteDevelopment , consulte a seção Configurar redirecionamentos permanentes na seção de produção . Use o HSTS para sinalizar aos clientes que somente solicitações de recursos seguras devem ser enviadas para o aplicativo (somente em produção).

Configuração da porta

Uma porta deve estar disponível para o middleware redirecionar uma solicitação insegura para HTTPS. Se nenhuma porta estiver disponível:

• O redirecionamento para HTTPS não ocorrerá.
• O middleware registra o aviso Falha ao determinar a porta https para redirecionamento.

Especifique a porta HTTPS usando qualquer uma das seguintes abordagens:

• Defina HttpsRedirectionOptions.HttpsPort.

• Defina a https_portconfiguração do host:

  • Na configuração do host.

  • Definindo a variável de ambiente ASPNETCORE_HTTPS_PORT.

  • Adicionando uma entrada de nível superior no arquivo appsettings.json :

    {
      "https_port": 443,
      "Logging": {
        "LogLevel": {
          "Default": "Information",
          "Microsoft.AspNetCore": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    

• Indique uma porta com o esquema seguro usando a variável de ambiente ASPNETCORE_URLS. A variável de ambiente configura o servidor. O middleware descobre indiretamente a porta HTTPS via IServerAddressesFeature. Essa abordagem não funciona em implantações de proxy reverso.

• Os modelos web ASP.NET Core definem uma URL HTTPS no arquivo Properties/launchsettings.json para Kestrel e IIS Express. O arquivo launchsettings.json é usado somente no computador local.

• Configure um ponto de extremidade de URL HTTPS para uma implantação de borda voltada para o público de um servidor Kestrel ou de um servidor HTTP.sys. Apenas uma porta HTTPS é usada pelo aplicativo. O middleware descobre a porta via IServerAddressesFeature.

Implantações em Edge

Quando Kestrel ou HTTP.sys é usado como um servidor de borda voltado para o público, Kestrel ou HTTP.sys deve ser configurado para escutar em ambos:

• A porta segura em que o cliente é redirecionado (normalmente, 443 em produção e 5001 em desenvolvimento).
• A porta insegura (normalmente, 80 em produção e 5000 em desenvolvimento).

A porta insegura deve ser acessível pelo cliente para que o aplicativo receba uma solicitação insegura e redirecione o cliente para a porta segura.

Para obter mais informações, consulte a Kestrel ou a implementação do servidor Web HTTP.sys no ASP.NET Core.

Cenários de implantação

Qualquer firewall entre o cliente e o servidor também deve ter portas de comunicação abertas para tráfego.

Se as solicitações forem encaminhadas em uma configuração de proxy reverso, use Middleware de Cabeçalhos Encaminhados antes de chamar o Middleware de Redirecionamento para HTTPS. O middleware de cabeçalhos encaminhados atualiza o Request.Scheme usando o cabeçalho X-Forwarded-Proto. O middleware permite que os URIs de redirecionamento e outras políticas de segurança funcionem corretamente. Quando o Forwarded Headers Middleware não é usado, a aplicação de back-end pode não receber o protocolo correto e ficar presa em um loop de redirecionamento. Uma mensagem de erro comum do usuário final é que há muitos redirecionamentos.

Ao implantar no Serviço de Aplicativo do Azure, siga as orientações em Habilitar HTTPS para um domínio personalizado no Serviço de Aplicativo do Azure.

Opções

O código realçado a seguir chama o AddHttpsRedirection método para configurar opções de middleware:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddHsts(options =>
{
    options.Preload = true;
    options.IncludeSubDomains = true;
    options.MaxAge = TimeSpan.FromDays(60);
    options.ExcludedHosts.Add("example.com");
    options.ExcludedHosts.Add("www.example.com");
});

builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = Status307TemporaryRedirect;
    options.HttpsPort = 5001;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Só é necessário chamar AddHttpsRedirection para alterar os valores de HttpsPort ou RedirectStatusCode.

O código destacado anterior:

• Define a HttpsRedirectionOptions.RedirectStatusCode propriedade para o Status307TemporaryRedirect código, que é o valor padrão. Use os campos da classe StatusCodes para atribuições a RedirectStatusCode.
• Define a porta HTTPS como 5001.

Configurar redirecionamentos permanentes na produção

O middleware usa como padrão o envio de um Status307TemporaryRedirect código com todos os redirecionamentos. Se preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente que não seja Development, envolva a configuração das opções do middleware em uma verificação condicional para um ambiente que não seja Development.

O código a seguir mostra a configuração de serviços no arquivo Program.cs :

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

if (!builder.Environment.IsDevelopment())
{
    builder.Services.AddHttpsRedirection(options =>
    {
        options.RedirectStatusCode = Status308PermanentRedirect;
        options.HttpsPort = 443;
    });
}

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");

    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Abordagem alternativa do Middleware de Redirecionamento para HTTPS

Uma alternativa ao uso do Middleware de Redirecionamento HTTPS (com o UseHttpsRedirection método) é usar o Middleware de Reescrita de URL (por meio do AddRedirectToHttps método). AddRedirectToHttps também pode definir o código de status e a porta quando o redirecionamento é executado. Para obter mais informações, consulte Middleware de Regravação de URL.

Quando o aplicativo redireciona para HTTPS sem a necessidade de outras regras de redirecionamento, a recomendação é usar o Middleware de Redirecionamento HTTPS (UseHttpsRedirection) conforme descrito neste artigo.

HSTS (Protocolo de Segurança do Transporte Estrito HTTP)

Por OWASP, o HSTS é um aprimoramento de segurança de aceitação especificado por um aplicativo Web por meio de um cabeçalho de resposta. Quando um navegador que dá suporte ao HSTS recebe esse cabeçalho:

• O navegador armazena a configuração para o domínio que impede o envio de qualquer comunicação por HTTP. O navegador força todas as comunicações via HTTPS.
• O navegador impede que o usuário use certificados não confiáveis ou inválidos. O navegador desabilita prompts que permitem que um usuário confie temporariamente nesse certificado.

Como o cliente impõe o HSTS, há algumas limitações:

• O cliente deve dar suporte ao HSTS.
• O HSTS requer pelo menos uma solicitação HTTPS bem-sucedida para estabelecer a política HSTS.
• O aplicativo deve verificar cada solicitação HTTP e redirecioná-la ou rejeitá-la.

O ASP.NET Core implementa o HSTS com o método de extensão UseHsts. O código a seguir chama UseHsts quando o aplicativo não está no modo de desenvolvimento:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

UseHsts não é recomendado no desenvolvimento porque as configurações do HSTS são altamente armazenáveis em cache por navegadores. Por padrão, UseHsts exclui o endereço de loopback local.

Para ambientes de produção que estão implementando HTTPS pela primeira vez, defina o valor da propriedade inicial HstsOptions.MaxAge como uma pequena quantidade usando um dos TimeSpan métodos. Defina o valor de horas para não mais do que um único dia, caso seja necessário reverter a infraestrutura HTTPS para HTTP. Depois de confiar na sustentabilidade da configuração HTTPS, aumente o valor do HSTS max-age (geralmente, um ano).

O seguinte código realçado:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddHsts(options =>
{
    options.Preload = true;
    options.IncludeSubDomains = true;
    options.MaxAge = TimeSpan.FromDays(60);
    options.ExcludedHosts.Add("example.com");
    options.ExcludedHosts.Add("www.example.com");
});

builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = Status307TemporaryRedirect;
    options.HttpsPort = 5001;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

• Define o parâmetro de pré-carregamento do cabeçalho Strict-Transport-Security. O pré-carregamento não faz parte da especificação do RFC 6797 HSTS. Os navegadores da Web dão suporte ao pré-carregamento de sites do HSTS na nova instalação. Para obter mais informações, consulte https://hstspreload.org/.
• Habilita a diretiva includeSubDomain, que aplica a política HSTS aos subdomínios do host. Para obter mais informações, consulte a especificação do RFC 6797 HSTS (Seção 6.1.2).
• Define explicitamente o parâmetro max-age do cabeçalho Strict-Transport-Security como 60 dias. Se não for definido, o padrão é de 30 dias. Para obter mais informações, consulte a max-age diretiva na especificação do RFC 6797 HSTS (Seção 6.1.1).
• Adiciona example.com à lista de hosts a serem excluídos.

UseHsts exclui os seguintes hosts de loopback:

• localhost: o endereço de loopback do IPv4.
• 127.0.0.1: o endereço de loopback IPv4.
• [::1]: o endereço de loopback IPv6.

Recusar HTTPS/HSTS na criação do projeto

Em alguns cenários de serviço de back-end em que a segurança de conexão é tratada na borda voltada para o público da rede, a configuração da segurança de conexão em cada nó não é necessária. Os aplicativos Web gerados com base nos modelos no Visual Studio ou no comando dotnet new habilitam o redirecionamento para HTTPS e o HSTS. Para implantações que não exigem esses cenários, você pode recusar HTTPS/HSTS quando o aplicativo é criado a partir do modelo.

Para recusar HTTPS/HSTS:

dotnet new webapp --no-https

Confiar no certificado de desenvolvimento HTTPS do ASP.NET Core

O SDK do .NET inclui um certificado de desenvolvimento HTTPS. O certificado é instalado como parte da experiência de primeira execução. Por exemplo, o dotnet --info comando produz uma variação da seguinte saída:

ASP.NET Core
------------
Successfully installed the ASP.NET Core HTTPS Development Certificate.
To trust the certificate run 'dotnet dev-certs https --trust' (Windows and macOS only).
For establishing trust on other platforms refer to the platform specific documentation.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.

A instalação do SDK do .NET instala o certificado de desenvolvimento HTTPS do ASP.NET Core no repositório de certificados do usuário local. O certificado está instalado, mas não é confiável. Para confiar no certificado, realize a etapa única a seguir para executar a ferramenta do dotnet dev-certs:

dotnet dev-certs https --trust

O comando a seguir fornece ajuda para a ferramenta dotnet dev-certs:

dotnet dev-certs https --help

Configurar o certificado do desenvolvedor para o Docker

Para configurar o certificado do desenvolvedor para Docker, consulte GitHub dotnet/aspnetcore.docs issue #6199 - Como configurar o certificado de desenvolvimento ao usar o Docker no desenvolvimento.

Considerações específicas do Linux

As distribuições do Linux diferem substancialmente na forma como marcam certificados como confiáveis.

dotnet dev-certs Espera-se que a ferramenta seja amplamente aplicável, mas o suporte oficial está disponível apenas para Ubuntu e Fedora. O suporte visa especificamente garantir a confiança em navegadores baseados em Firefox e Chromium (Microsoft Edge, Chrome e Chromium).

Dependencies

• Para estabelecer a confiança do OpenSSL, a ferramenta openssl deve estar no caminho.
• Para estabelecer a confiança no navegador (por exemplo, no Microsoft Edge ou no Firefox), a ferramenta certutil deve estar no PATH.

Confiança do OpenSSL

Quando um certificado de desenvolvimento ASP.NET Core é confiável, o certificado é exportado para uma pasta no diretório base do usuário atual. Para que o OpenSSL (e os clientes que o consomem) obtenham essa pasta, você precisa definir a variável de ambiente SSL_CERT_DIR. Você pode definir a variável em uma única sessão executando um comando como export SSL_CERT_DIR=$HOME/.aspnet/dev-certs/trust:/usr/lib/ssl/certs (o valor exato está na saída quando --verbose é passado) ou adicionando seu arquivo de configuração (distro e shell específico) (por exemplo , .profile).

Essa abordagem é necessária para fazer com que ferramentas como curl confiem no certificado de desenvolvimento. Como alternativa, você pode passar -CAfile ou -CApath para cada invocação individual curl .

Se o armazenamento de confiança do OpenSSL entrar em um estado incorreto (por exemplo, se dotnet dev-certs https --clean não conseguir removê-lo), muitas vezes é possível resolver o problema usando a ferramenta c_rehash.

Overrides

Se você estiver usando outro navegador com seu próprio repositório NSS (Serviços de Segurança de Rede), poderá usar a DOTNET_DEV_CERTS_NSSDB_PATHS variável de ambiente para especificar uma lista delimitada por dois pontos de diretórios do NSS (por exemplo, o diretório que cert9.dbcontém). Em seguida, você pode adicionar o local do certificado de desenvolvimento à lista na variável.

Se você armazenar os certificados em que deseja que o OpenSSL confie em um diretório específico, poderá usar a DOTNET_DEV_CERTS_OPENSSL_CERTIFICATE_DIRECTORY variável de ambiente para indicar o local do certificado.

Usando sudo

Como em outras plataformas, os certificados de desenvolvimento são armazenados e confiáveis separadamente para cada usuário.

Se você executar dotnet dev-certs como um usuário diferente (por exemplo, usando sudo), esse usuário específico (por exemplo root) confiará no certificado de desenvolvimento.

Confiar no certificado HTTPS no Linux com linux-dev-certs

linux-dev-certs é uma ferramenta global .NET de software livre, com suporte para a comunidade, que fornece uma maneira conveniente de criar e confiar em um certificado de desenvolvedor no Linux. Microsoft não mantém nem dá suporte à ferramenta.

Os comandos a seguir instalam a ferramenta e criam um certificado de desenvolvedor confiável:

dotnet tool update -g linux-dev-certs
dotnet linux-dev-certs install

Para obter mais informações ou relatar problemas, consulte o repositório GitHub linux-dev-certs.

SUSE Linux Enterprise Server (SLES Linux)

Se sua configuração incluir o SUSE Linux Enterprise Server, consulte GitHub dotnet/aspnetcore.docs issue #28292 - Trust HTTPS certificate on SLES.

Solucionar problemas de certificado (certificado não confiável)

Às vezes, quando um certificado de desenvolvimento HTTPS ASP.NET Core é instalado e confiável, o navegador avisa que o certificado não é confiável. As seções a seguir fornecem ajuda para solucionar esse problema.

O certificado de desenvolvimento HTTPS do ASP.NET Core é usado por Kestrel.

Para reparar o certificado do IIS Express, consulte o problema do Stack Overflow #20036984/answer #20048613 - Como restaurar um certificado SSL do IIS Express ausente?

Todas as plataformas – certificado não confiável

Para todas as plataformas, tente resolver os problemas de certificado não confiáveis com as seguintes etapas:

1. Execute os seguintes comandos:

   dotnet dev-certs https --clean
   dotnet dev-certs https --trust
   

2. Feche todas as instâncias abertas do navegador e abra o aplicativo em uma nova janela do navegador.

   O cache do navegador armazena se um certificado é confiável. O processo de fechamento/abertura ajuda a atualizar as configurações de cache do navegador para certificados.

Os dotnet dev-certs https comandos geralmente resolvem a maioria dos problemas de confiança do navegador. Se o dotnet dev-certs https --clean comando falhar e o navegador ainda não confiar no certificado, experimente as sugestões específicas da plataforma nas seções a seguir.

Docker – certificado não confiável

Se você estiver usando o Docker, tente resolver o problema com as seguintes etapas:

1. Exclua a pasta C:\Users{USER}\AppData\Roaming\ASP.NET\Https.

2. Limpe a solução. Exclua as pastas bin e obj.

3. Reinicie a ferramenta de desenvolvimento. Por exemplo, o Visual Studio ou o Visual Studio Code.

Windows – certificado não confiável

Se você estiver trabalhando no Windows, conclua as seguintes etapas de solução de problemas:

1. Verifique os certificados no repositório de certificados. Procure um certificado localhost com o nome ASP.NET Core HTTPS development certificate amigável em duas pastas:

   • Certificados pessoais > do usuário > atual
   • Usuário atual > Autoridades de certificação raiz confiáveis > Certificados

2. Remova todos os certificados das autoridades de certificação raiz pessoais e confiáveis.

   Important

   Não remova o certificado localhost do IIS Express.

3. Execute os seguintes comandos:

   dotnet dev-certs https --clean
   dotnet dev-certs https --trust
   

4. Feche todas as instâncias abertas do navegador e abra o aplicativo em uma nova janela do navegador.

OS X – certificado não confiável

Se você estiver trabalhando com o OS X, tente resolver o problema com as seguintes etapas:

1. Abra o KeyChain Access e, em seguida, selecione o conjunto de chaves do sistema.

2. Verifique a presença de um certificado localhost.

3. Confirme se o certificado mostra o símbolo de adição (+) no ícone, o que indica que o certificado é confiável para todos os usuários.

4. Remova o certificado do conjunto de chaves do sistema.

5. Execute os seguintes comandos:

   dotnet dev-certs https --clean
   dotnet dev-certs https --trust
   

6. Feche todas as instâncias abertas do navegador e abra o aplicativo em uma nova janela do navegador.

Para obter mais informações sobre como solucionar problemas com certificados no Visual Studio, consulte problema #16892 do dotnet/aspnetcore no GitHub) - Erro de HTTPS ao usar o IIS Express.

Linux – certificado não confiável

Se você estiver executando o Linux, siga estas etapas para solucionar problemas do certificado não confiável:

1. Confirme se o certificado que você está investigando é o certificado de desenvolvedor HTTPS do usuário planejado para uso pelo Kestrel servidor.

2. Verifique o certificado Kestrel de desenvolvedor HTTPS padrão do usuário atual no seguinte local:

   ls -la ~/.dotnet/corefx/cryptography/x509stores/my
   

   O arquivo de certificado Kestrel de desenvolvedor HTTPS é a impressão digital SHA1. Quando o arquivo é excluído com o dotnet dev-certs https --clean comando, o arquivo é regenerado quando necessário com uma impressão digital diferente.

3. Verifique se a impressão digital do certificado exportado corresponde executando o seguinte comando:

   openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt
   

   Se a impressão digital do certificado não corresponder, investigue as seguintes condições:

   • Verifique se o certificado é antigo.

   • Verifique se o certificado é um certificado de desenvolvedor exportado para o usuário raiz.

     • Se for, exporte o certificado.

4. Verifique o certificado do usuário raiz na seguinte pasta:

   ls -la /root/.dotnet/corefx/cryptography/x509stores/my
   

Certificado SSL do IIS Express usado com o Visual Studio

Para corrigir problemas com o certificado IIS Express, selecione Repair no instalador do Visual Studio. Para obter mais informações, consulte o problema do GitHub no dotnet/aspnetcore #16892) - Erro de HTTPS ao usar o IIS Express.

A política de grupo impede a confiança de certificados autoassinados

Em alguns casos, a política de grupo pode impedir que certificados autoassinados sejam confiáveis. Para obter mais informações, consulte GitHub dotnet/aspnetcore issue #21173 - Error que confia no certificado de desenvolvedor HTTPS.

Conteúdo relacionado

• Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga
• Host ASP.NET Core no Linux com Nginx: configuração HTTPS
• Configurar o SSL no IIS 7 ou posterior
• Configurar pontos de extremidade para o Kestrel servidor Web
• Suporte ao navegador HSTS do OWASP

O redirecionamento HTTP para HTTPS causa ERR_INVALID_REDIRECT na solicitação de simulação do CORS

Solicitações para um ponto de extremidade usando HTTP que são redirecionadas para HTTPS por falha de UseHttpsRedirection com ERR_INVALID_REDIRECT na solicitação de simulação CORS.

Os projetos de API podem rejeitar solicitações HTTP em vez de usar UseHttpsRedirection para redirecionar solicitações para HTTPS.

Exigir HTTPS

Recomendamos que os aplicativos Web do ASP.NET Core de produção usem:

• Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) para redirecionar as solicitações HTTP para HTTPS.
• Middleware HSTS (UseHsts) para enviar cabeçalhos HSTS (Protocolo de Segurança do Transporte Estrito HTTP) para clientes.

UseHttpsRedirection

O seguinte código chama UseHttpsRedirection no arquivo Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

O código destacado anterior:

• Usa o padrão HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
• Usa o padrão HttpsRedirectionOptions.HttpsPort (nulo), a menos que seja substituído pela variável de ambiente ASPNETCORE_HTTPS_PORT ou IServerAddressesFeature.

É recomendável usar redirecionamentos temporários em vez de redirecionamentos permanentes. O cache de link pode causar um comportamento instável em ambientes de desenvolvimento. Se você preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente diferenteDevelopment , consulte a seção Configurar redirecionamentos permanentes na seção de produção . É recomendável usar o HSTS para sinalizar aos clientes que apenas solicitações de recursos seguras devem ser enviadas para o aplicativo (somente em produção).

Configuração da porta

Uma porta deve estar disponível para o middleware redirecionar uma solicitação insegura para HTTPS. Se nenhuma porta estiver disponível:

• O redirecionamento para HTTPS não ocorrerá.
• O middleware registrará o aviso "Falha ao determinar a porta https para redirecionamento".

Especifique a porta HTTPS usando qualquer uma das seguintes abordagens:

• Defina HttpsRedirectionOptions.HttpsPort.

• Defina a https_portconfiguração do host:

  • Na configuração do host.

  • Definindo a variável de ambiente ASPNETCORE_HTTPS_PORT.

  • Adicionando uma entrada de nível superior em appsettings.json:

    {
      "https_port": 443,
      "Logging": {
        "LogLevel": {
          "Default": "Information",
          "Microsoft.AspNetCore": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    

• Indique uma porta com o esquema seguro usando a variável de ambiente ASPNETCORE_URLS. A variável de ambiente configura o servidor. O middleware descobre indiretamente a porta HTTPS via IServerAddressesFeature. Essa abordagem não funciona em implantações de proxy reverso.

• Os modelos Web do ASP.NET Core definem uma URL HTTPS em Properties/launchsettings.json para Kestrel e para o IIS Express. launchsettings.json é usado apenas no computador local.

• Configure um ponto de extremidade de URL HTTPS para uma implantação de borda voltada para o público de um servidor Kestrel ou de um servidor HTTP.sys. Apenas uma porta HTTPS é usada pelo aplicativo. O middleware descobre a porta via IServerAddressesFeature.

Implantações em Edge

Quando Kestrel ou HTTP.sys é usado como um servidor de borda voltado para o público, Kestrel ou HTTP.sys deve ser configurado para escutar em ambos:

• A porta segura em que o cliente é redirecionado (normalmente, 443 em produção e 5001 em desenvolvimento).
• A porta insegura (normalmente, 80 em produção e 5000 em desenvolvimento).

A porta insegura deve ser acessível ao cliente para que o aplicativo receba uma solicitação insegura e redirecione o cliente para a porta segura.

Para obter mais informações, consulte a Kestrel ou a implementação do servidor Web HTTP.sys no ASP.NET Core.

Cenários de implantação

Qualquer firewall entre o cliente e o servidor também deve ter portas de comunicação abertas para tráfego.

Se as solicitações forem encaminhadas em uma configuração de proxy reverso, use Middleware de Cabeçalhos Encaminhados antes de chamar o Middleware de Redirecionamento para HTTPS. O Middleware de Cabeçalhos Encaminhados atualiza o Request.Scheme, usando o cabeçalho X-Forwarded-Proto. O middleware permite que os URIs de redirecionamento e outras políticas de segurança funcionem corretamente. Quando o Middleware de Cabeçalhos Encaminhados não é usado, o aplicativo de back-end pode não receber o esquema correto e acabar em um loop de redirecionamento. Uma mensagem de erro comum ao usuário final é que ocorreram muitos redirecionamentos.

Ao implantar no Serviço de Aplicativo do Azure, siga as diretrizes no Tutorial: Associar um certificado SSL personalizado existente aos Aplicativos Web do Azure.

Opções

O código realçado a seguir chama AddHttpsRedirection para configurar opções de middleware:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddHsts(options =>
{
    options.Preload = true;
    options.IncludeSubDomains = true;
    options.MaxAge = TimeSpan.FromDays(60);
    options.ExcludedHosts.Add("example.com");
    options.ExcludedHosts.Add("www.example.com");
});

builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = Status307TemporaryRedirect;
    options.HttpsPort = 5001;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Só é necessário chamar AddHttpsRedirection para alterar os valores de HttpsPort ou RedirectStatusCode.

O código destacado anterior:

• Define HttpsRedirectionOptions.RedirectStatusCode como Status307TemporaryRedirect, que é o valor padrão. Use os campos da classe StatusCodes para atribuições a RedirectStatusCode.
• Define a porta HTTPS como 5001.

Configurar redirecionamentos permanentes na produção

O middleware tem como padrão o envio de um Status307TemporaryRedirect com todos os redirecionamentos. Se preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente que não seja Development, envolva a configuração das opções do middleware em uma verificação condicional para um ambiente que não seja Development.

Ao configurar serviços em Program.cs:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

if (!builder.Environment.IsDevelopment())
{
    builder.Services.AddHttpsRedirection(options =>
    {
        options.RedirectStatusCode = Status308PermanentRedirect;
        options.HttpsPort = 443;
    });
}

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");

    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Abordagem alternativa do Middleware de Redirecionamento para HTTPS

Uma alternativa ao uso do Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) é usar o Middleware de Regravação de URL (AddRedirectToHttps). AddRedirectToHttps também pode definir o código de status e a porta quando o redirecionamento é executado. Para obter mais informações, consulte Middleware de Regravação de URL.

Ao redirecionar para HTTPS sem a necessidade de regras de redirecionamento adicionais, é recomendável usar o Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) descrito nesse artigo.

HSTS (Protocolo de Segurança do Transporte Estrito HTTP)

De acordo com o OWASP, o HSTS (Segurança do Transporte Estrito HTTP é um aperfeiçoamento de segurança opcional, que é especificado por um aplicativo Web por meio de um cabeçalho de resposta. Quando um navegador que dá suporte ao HSTS recebe esse cabeçalho:

• O navegador armazena a configuração para o domínio que impede o envio de qualquer comunicação por HTTP. O navegador força todas as comunicações via HTTPS.
• O navegador impede que o usuário use certificados não confiáveis ou inválidos. O navegador desabilita prompts que permitem que um usuário confie temporariamente nesse certificado.

Como o HSTS é imposto pelo cliente, ele tem algumas limitações:

• O cliente deve dar suporte ao HSTS.
• O HSTS requer pelo menos uma solicitação HTTPS bem-sucedida para estabelecer a política HSTS.
• O aplicativo deve verificar cada solicitação HTTP e redirecioná-la ou rejeitá-la.

O ASP.NET Core implementa o HSTS com o método de extensão UseHsts. O código a seguir chama UseHsts quando o aplicativo não está no modo de desenvolvimento:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

UseHsts não é recomendado no desenvolvimento porque as configurações do HSTS são altamente armazenáveis em cache por navegadores. Por padrão, UseHsts exclui o endereço de loopback local.

Para ambientes de produção que estão implementando HTTPS pela primeira vez, defina o HstsOptions.MaxAge inicial como um valor pequeno usando um dos métodos TimeSpan. Defina o valor de horas para não mais do que um único dia, caso precise reverter a infraestrutura HTTPS para HTTP. Depois de ter certeza da sustentabilidade da configuração HTTPS, aumente o valor max-age do HSTS; um valor comumente usado é um ano.

O seguinte código realçado:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddHsts(options =>
{
    options.Preload = true;
    options.IncludeSubDomains = true;
    options.MaxAge = TimeSpan.FromDays(60);
    options.ExcludedHosts.Add("example.com");
    options.ExcludedHosts.Add("www.example.com");
});

builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = Status307TemporaryRedirect;
    options.HttpsPort = 5001;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

• Define o parâmetro de pré-carregamento do cabeçalho Strict-Transport-Security. O preload não faz parte da especificação RFC HSTS, mas é suportado por navegadores para pré-carregar sites HSTS em uma nova instalação. Para obter mais informações, consulte https://hstspreload.org/.
• Habilita includeSubDomain, que aplica a política do HSTS aos subdomínios do Host.
• Define explicitamente o parâmetro max-age do cabeçalho Strict-Transport-Security como 60 dias. Se não for definido, será de 30 dias por padrão. Para saber mais, confira a diretiva de idade máxima.
• Adiciona example.com à lista de hosts a serem excluídos.

UseHsts exclui os seguintes hosts de loopback:

• localhost : o endereço de loopback IPv4.
• 127.0.0.1 : o endereço de loopback IPv4.
• [::1] : o endereço de loopback IPv6.

Recusar HTTPS/HSTS na criação do projeto

Em alguns cenários de serviço de back-end em que a segurança da conexão é tratada na borda voltada para o público da rede, a configuração da segurança de conexão em cada nó não é necessária. Os aplicativos Web gerados com base nos modelos no Visual Studio ou no comando dotnet new habilitam o redirecionamento para HTTPS e o HSTS. Para implantações que não exigem esses cenários, você pode recusar o HTTPS/HSTS quando o aplicativo é criado com base no modelo.

Para recusar HTTPS/HSTS:

dotnet new webapp --no-https

Confiar no certificado de desenvolvimento HTTPS do ASP.NET Core no Windows e macOS

Para o navegador Firefox, consulte a próxima seção.

O SDK do .NET Core inclui um certificado de desenvolvimento HTTPS. O certificado é instalado como parte da experiência de primeira execução. Por exemplo, dotnet --info produz uma variação da saída a seguir:

ASP.NET Core
------------
Successfully installed the ASP.NET Core HTTPS Development Certificate.
To trust the certificate run 'dotnet dev-certs https --trust' (Windows and macOS only).
For establishing trust on other platforms refer to the platform specific documentation.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.

Instalar o SDK do .NET Core instala o certificado de desenvolvimento HTTPS do ASP.NET Core no repositório de certificados do usuário local. O certificado foi instalado, mas não é confiável. Para confiar no certificado, realize a etapa única a seguir para executar a ferramenta do dotnet dev-certs:

dotnet dev-certs https --trust

O comando a seguir fornece ajuda para a ferramenta dotnet dev-certs:

dotnet dev-certs https --help

Confiar no certificado HTTPS com o Firefox para evitar o erro SEC_ERROR_INADEQUATE_KEY_USAGE

O navegador Firefox usa seu próprio repositório de certificados e, portanto, não confia nos certificados de desenvolvedor IIS Express ou Kestrel.

Há duas abordagens para confiar no certificado HTTPS com o Firefox: criar um arquivo de política ou configurar com o navegador FireFox. A configuração com o navegador cria o arquivo de política, para que as duas abordagens sejam equivalentes.

Criar um arquivo de política para confiar no certificado HTTPS com o Firefox

Crie um arquivo de política (policies.json) em:

• Windows: %PROGRAMFILES%\Mozilla Firefox\distribution\
• Macos: Firefox.app/Contents/Resources/distribution
• Linux: veja Confiar no certificado com o Firefox no Linux neste artigo.

Adicione o seguinte JSON ao arquivo de política do Firefox:

{
  "policies": {
    "Certificates": {
      "ImportEnterpriseRoots": true
    }
  }
}

O arquivo de política mencionado faz com que o Firefox confie em certificados do repositório de certificados do Windows. A próxima seção fornece uma abordagem alternativa para criar o arquivo de política anterior usando o navegador Firefox.

Configurar a confiança do certificado HTTPS usando o navegador Firefox

Defina security.enterprise_roots.enabled = true usando as seguintes instruções:

1. Insira about:config no navegador Firefox.
2. Selecione Aceitar o Risco e Continuar se você aceitar o risco.
3. Selecione Mostrar Tudo
4. Defina security.enterprise_roots.enabled = true
5. Saia e reinicie o Firefox

Para obter mais informações, consulte Configurando Autoridades de Certificação (ACs) no Firefox e o arquivo mozilla/policy-templates/README.

Como configurar um certificado de desenvolvedor para o Docker

Consulte este problema do GitHub.

Confiar no certificado HTTPS no Linux

O estabelecimento de confiança é específico da distribuição e do navegador. As seções a seguir fornecem instruções para algumas distribuições populares e os navegadores Chromium (Edge e Chrome) e para o Firefox.

O Ubuntu confia no certificado para comunicação serviço a serviço

As instruções a seguir não funcionam para algumas versões do Ubuntu, como a 20.04. Para obter mais informações, consulte o problema dotnet/AspNetCore.Docs #23686 do GitHub.

1. Instale o OpenSSL 1.1.1h ou posterior. Consulte sua distribuição para obter instruções sobre como atualizar o OpenSSL.

2. Execute os seguintes comandos:

   dotnet dev-certs https
   sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM
   sudo update-ca-certificates
   

Os comandos anteriores:

• Verifique se o certificado de desenvolvedor do usuário atual foi criado.
• Exporta o certificado com permissões elevadas necessárias para a pasta ca-certificates, usando o ambiente do usuário atual.
• A remoção do sinalizador -E exporta o certificado do usuário raiz, gerando-o, se necessário. Cada certificado recém-gerado tem uma impressão digital diferente. Ao executar como raiz, sudo e -E não são necessários.

O caminho no comando anterior é específico para o Ubuntu. Para outras distribuições, selecione um caminho apropriado ou use o caminho para as Autoridades de Certificação (ACs).

Confiar no certificado HTTPS no Linux usando o Edge ou o Chrome

cat <<EOF | sudo tee /usr/lib/firefox/distribution/policies.json
{
    "policies": {
        "Certificates": {
            "Install": [
                "/usr/local/share/ca-certificates/aspnet/https.crt"
            ]
        }
    }
}
EOF

dnf install nss-tools

cd ${ProjectDirectory}
dotnet dev-certs https -ep ${ProjectDirectory}/${CertificateName}.crt --format PEM

certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt

certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "P,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt

alias curl="curl --cacert ${ProjectDirectory}/${CertificateName}.crt"

certutil -d sql:$HOME/.pki/nssdb -D -n ${CertificateName}
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -D -n ${CertificateName}
rm ${ProjectDirectory}/${CertificateName}.crt
dotnet dev-certs https --clean

Confiar no certificado com Fedora 34

See:

• Este comentário do GitHub
• Fedora: usando certificados de sistema compartilhados
• Configurar um ambiente de desenvolvimento do .NET no Fedora.

Confiar no certificado com outras distribuições

Consulte este problema do GitHub.

Confiar no certificado HTTPS do Subsistema do Windows para Linux

As instruções a seguir não funcionam para algumas distribuições do Linux, como o Ubuntu 20.04. Para obter mais informações, consulte o problema dotnet/AspNetCore.Docs #23686 do GitHub.

O WSL (Subsistema do Windows para Linux) gera um certificado de desenvolvimento autoassinado HTTPS, que por padrão não é confiável no Windows. A maneira mais fácil de fazer com que o Windows confie no certificado WSL é configurar o WSL para usar o mesmo certificado que o Windows:

• No Windows, exporte o certificado do desenvolvedor para um arquivo:

  dotnet dev-certs https -ep https.pfx -p $CREDENTIAL_PLACEHOLDER$ --trust
  

  Em que $CREDENTIAL_PLACEHOLDER$ é uma senha.

• Em uma janela WSL, importe o certificado exportado na instância do WSL:

  dotnet dev-certs https --clean --import <<path-to-pfx>> --password $CREDENTIAL_PLACEHOLDER$
  

A abordagem anterior é uma operação única por certificado e por distribuição WSL. É mais fácil do que exportar o certificado repetidas vezes. Se você atualizar ou regenerar o certificado no Windows, talvez seja necessário executar os comandos anteriores novamente.

Solucionar problemas de certificado, como certificado não confiável

Esta seção fornece ajuda quando o certificado de desenvolvimento HTTPS do ASP.NET Core foi instalado e é confiável, mas você ainda tem avisos do navegador de que o certificado não é confiável. O certificado de desenvolvimento HTTPS do ASP.NET Core é usado por Kestrel.

Para reparar o certificado IIS Express, consulte esse problema do Stackoverflow.

Todas as plataformas – certificado não confiável

Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo. A confiança do certificado é armazenada em cache por navegadores.

Falha em dotnet dev-certs https --clean

Os comandos anteriores resolvem a maioria dos problemas de confiança do navegador. Se o navegador ainda não estiver confiando no certificado, siga as sugestões específicas da plataforma a seguir.

Docker – certificado não confiável

• Exclua a pasta C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
• Limpe a solução. Exclua as pastas bin e obj.
• Reinicie a ferramenta de desenvolvimento. Por exemplo, o Visual Studio ou o Visual Studio Code.

Windows – certificado não confiável

• Verifique os certificados no repositório de certificados. Deve haver um certificado localhost com o nome amigável ASP.NET Core HTTPS development certificate em Current User > Personal > Certificates e Current User > Trusted root certification authorities > Certificates
• Remova todos os certificados encontrados das autoridades de certificação raiz pessoais e confiáveis. Não remova o certificado localhost do IIS Express.
• Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo.

OS X – certificado não confiável

• Abra o Acesso ao Conjunto de Chaves.
• Selecione o conjunto de chaves do sistema.
• Verifique a presença de um certificado localhost.
• Verifique se ele contém um símbolo + no ícone para indicar que ele é confiável para todos os usuários.
• Remova o certificado do conjunto de chaves do sistema.
• Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo.

Consulte Erro HTTPS usando IIS Express (dotnet/AspNetCore #16892) para solucionar problemas de certificado com o Visual Studio.

Certificado do Linux não confiável

Verifique se o certificado que está sendo configurado para confiança é o certificado de desenvolvedor HTTPS do usuário que será usado pelo servidor Kestrel.

Verifique o certificado Kestrel de desenvolvedor HTTPS padrão do usuário atual no seguinte local:

ls -la ~/.dotnet/corefx/cryptography/x509stores/my

O arquivo de certificado Kestrel de desenvolvedor HTTPS é a impressão digital SHA1. Quando o arquivo é excluído via dotnet dev-certs https --clean, ele é regenerado quando necessário com uma impressão digital diferente. Verifique se a impressão digital do certificado exportado corresponde ao seguinte comando:

openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt

Se o certificado não corresponder, ele poderá ser um dos seguintes:

• Um certificado antigo.
• Um certificado de desenvolvedor exportado para o usuário raiz. Nesse caso, exporte o certificado.

O certificado do usuário raiz pode ser verificado em:

ls -la /root/.dotnet/corefx/cryptography/x509stores/my

Certificado SSL do IIS Express usado com o Visual Studio

Para corrigir problemas com o certificado do IIS Express, selecione Reparar no instalador do Visual Studio. Saiba mais neste tópico do GitHub.

A política de grupo impede que certificados autoassinados sejam confiáveis

Em alguns casos, a política de grupo pode impedir que certificados autoassinados sejam confiáveis. Saiba mais neste tópico do GitHub.

Informações adicionais

• Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga
• Host ASP.NET Core no Linux com Nginx: configuração HTTPS
• Como configurar o SSL no IIS
• Configurar pontos de extremidade para o Kestrel servidor Web
• Suporte ao navegador HSTS do OWASP

Exigir HTTPS

Recomendamos que os aplicativos Web do ASP.NET Core de produção usem:

• Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) para redirecionar as solicitações HTTP para HTTPS.
• Middleware HSTS (UseHsts) para enviar cabeçalhos HSTS (Protocolo de Segurança do Transporte Estrito HTTP) para clientes.

UseHttpsRedirection

O código a seguir chama UseHttpsRedirection na classe Startup:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

O código destacado anterior:

• Usa o padrão HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
• Usa o padrão HttpsRedirectionOptions.HttpsPort (nulo), a menos que seja substituído pela variável de ambiente ASPNETCORE_HTTPS_PORT ou IServerAddressesFeature.

É recomendável usar redirecionamentos temporários em vez de redirecionamentos permanentes. O cache de link pode causar um comportamento instável em ambientes de desenvolvimento. Se você preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente diferenteDevelopment , consulte a seção Configurar redirecionamentos permanentes na seção de produção . É recomendável usar o HSTS para sinalizar aos clientes que apenas solicitações de recursos seguras devem ser enviadas para o aplicativo (somente em produção).

Configuração da porta

Uma porta deve estar disponível para o middleware redirecionar uma solicitação insegura para HTTPS. Se nenhuma porta estiver disponível:

• O redirecionamento para HTTPS não ocorrerá.
• O middleware registrará o aviso "Falha ao determinar a porta https para redirecionamento".

Especifique a porta HTTPS usando qualquer uma das seguintes abordagens:

• Defina HttpsRedirectionOptions.HttpsPort.

• Defina a https_portconfiguração do host:

  • Na configuração do host.

  • Definindo a variável de ambiente ASPNETCORE_HTTPS_PORT.

  • Adicionando uma entrada de nível superior em appsettings.json:

    {
        "https_port": 443,
        "Logging": {
            "LogLevel": {
                "Default": "Information",
                "Microsoft": "Warning",
                "Microsoft.Hosting.Lifetime": "Information"
            }
        },
        "AllowedHosts": "*"
    }
    

• Indique uma porta com o esquema seguro usando a variável de ambiente ASPNETCORE_URLS. A variável de ambiente configura o servidor. O middleware descobre indiretamente a porta HTTPS via IServerAddressesFeature. Essa abordagem não funciona em implantações de proxy reverso.

• No desenvolvimento, defina uma URL HTTPS em launchsettings.json. Habilite o HTTPS quando o IIS Express for usado.

• Configure um ponto de extremidade de URL HTTPS para uma implantação de borda voltada para o público de um servidor Kestrel ou de um servidor HTTP.sys. Apenas uma porta HTTPS é usada pelo aplicativo. O middleware descobre a porta via IServerAddressesFeature.

Implantações em Edge

Quando Kestrel ou HTTP.sys é usado como um servidor de borda voltado para o público, Kestrel ou HTTP.sys deve ser configurado para escutar em ambos:

• A porta segura em que o cliente é redirecionado (normalmente, 443 em produção e 5001 em desenvolvimento).
• A porta insegura (normalmente, 80 em produção e 5000 em desenvolvimento).

A porta insegura deve ser acessível ao cliente para que o aplicativo receba uma solicitação insegura e redirecione o cliente para a porta segura.

Para obter mais informações, consulte a Kestrel ou a implementação do servidor Web HTTP.sys no ASP.NET Core.

Cenários de implantação

Qualquer firewall entre o cliente e o servidor também deve ter portas de comunicação abertas para tráfego.

Se as solicitações forem encaminhadas em uma configuração de proxy reverso, use Middleware de Cabeçalhos Encaminhados antes de chamar o Middleware de Redirecionamento para HTTPS. O Middleware de Cabeçalhos Encaminhados atualiza o Request.Scheme, usando o cabeçalho X-Forwarded-Proto. O middleware permite que os URIs de redirecionamento e outras políticas de segurança funcionem corretamente. Quando o Middleware de Cabeçalhos Encaminhados não é usado, o aplicativo de back-end pode não receber o esquema correto e acabar em um loop de redirecionamento. Uma mensagem de erro comum ao usuário final é que ocorreram muitos redirecionamentos.

Ao implantar no Serviço de Aplicativo do Azure, siga as diretrizes no Tutorial: Associar um certificado SSL personalizado existente aos Aplicativos Web do Azure.

Opções

O código realçado a seguir chama AddHttpsRedirection para configurar opções de middleware:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();

    services.AddHsts(options =>
    {
        options.Preload = true;
        options.IncludeSubDomains = true;
        options.MaxAge = TimeSpan.FromDays(60);
        options.ExcludedHosts.Add("example.com");
        options.ExcludedHosts.Add("www.example.com");
    });

    services.AddHttpsRedirection(options =>
    {
        options.RedirectStatusCode = (int) HttpStatusCode.TemporaryRedirect;
        options.HttpsPort = 5001;
    });
}

Só é necessário chamar AddHttpsRedirection para alterar os valores de HttpsPort ou RedirectStatusCode.

O código destacado anterior:

• Define HttpsRedirectionOptions.RedirectStatusCode como Status307TemporaryRedirect, que é o valor padrão. Use os campos da classe StatusCodes para atribuições a RedirectStatusCode.
• Define a porta HTTPS como 5001.

Configurar redirecionamentos permanentes na produção

O middleware tem como padrão o envio de um Status307TemporaryRedirect com todos os redirecionamentos. Se preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente que não seja Development, envolva a configuração das opções do middleware em uma verificação condicional para um ambiente que não seja Development.

Ao configurar serviços em Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    // IWebHostEnvironment (stored in _env) is injected into the Startup class.
    if (!_env.IsDevelopment())
    {
        services.AddHttpsRedirection(options =>
        {
            options.RedirectStatusCode = (int) HttpStatusCode.PermanentRedirect;
            options.HttpsPort = 443;
        });
    }
}

Abordagem alternativa do Middleware de Redirecionamento para HTTPS

Uma alternativa ao uso do Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) é usar o Middleware de Regravação de URL (AddRedirectToHttps). AddRedirectToHttps também pode definir o código de status e a porta quando o redirecionamento é executado. Para obter mais informações, consulte Middleware de Regravação de URL.

Ao redirecionar para HTTPS sem a necessidade de regras de redirecionamento adicionais, é recomendável usar o Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) descrito nesse artigo.

HSTS (Protocolo de Segurança do Transporte Estrito HTTP)

De acordo com o OWASP, o HSTS (Segurança do Transporte Estrito HTTP é um aperfeiçoamento de segurança opcional, que é especificado por um aplicativo Web por meio de um cabeçalho de resposta. Quando um navegador que dá suporte ao HSTS recebe esse cabeçalho:

• O navegador armazena a configuração para o domínio que impede o envio de qualquer comunicação por HTTP. O navegador força todas as comunicações via HTTPS.
• O navegador impede que o usuário use certificados não confiáveis ou inválidos. O navegador desabilita prompts que permitem que um usuário confie temporariamente nesse certificado.

Como o HSTS é imposto pelo cliente, ele tem algumas limitações:

• O cliente deve dar suporte ao HSTS.
• O HSTS requer pelo menos uma solicitação HTTPS bem-sucedida para estabelecer a política HSTS.
• O aplicativo deve verificar cada solicitação HTTP e redirecioná-la ou rejeitá-la.

O ASP.NET Core implementa o HSTS com o método de extensão UseHsts. O código a seguir chama UseHsts quando o aplicativo não está no modo de desenvolvimento:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    else
    {
        app.UseExceptionHandler("/Error");
        // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
        app.UseHsts();
    }

    app.UseHttpsRedirection();
    app.UseStaticFiles();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
    });
}

UseHsts não é recomendado no desenvolvimento porque as configurações do HSTS são altamente armazenáveis em cache por navegadores. Por padrão, UseHsts exclui o endereço de loopback local.

Para ambientes de produção que estão implementando HTTPS pela primeira vez, defina o HstsOptions.MaxAge inicial como um valor pequeno usando um dos métodos TimeSpan. Defina o valor de horas para não mais do que um único dia, caso precise reverter a infraestrutura HTTPS para HTTP. Depois de ter certeza da sustentabilidade da configuração HTTPS, aumente o valor max-age do HSTS; um valor comumente usado é um ano.

O seguinte código:

public void ConfigureServices(IServiceCollection services)
{
    services.AddRazorPages();

    services.AddHsts(options =>
    {
        options.Preload = true;
        options.IncludeSubDomains = true;
        options.MaxAge = TimeSpan.FromDays(60);
        options.ExcludedHosts.Add("example.com");
        options.ExcludedHosts.Add("www.example.com");
    });

    services.AddHttpsRedirection(options =>
    {
        options.RedirectStatusCode = (int) HttpStatusCode.TemporaryRedirect;
        options.HttpsPort = 5001;
    });
}

• Define o parâmetro de pré-carregamento do cabeçalho Strict-Transport-Security. O preload não faz parte da especificação RFC HSTS, mas é suportado por navegadores para pré-carregar sites HSTS em uma nova instalação. Para obter mais informações, consulte https://hstspreload.org/.
• Habilita includeSubDomain, que aplica a política do HSTS aos subdomínios do Host.
• Define explicitamente o parâmetro max-age do cabeçalho Strict-Transport-Security como 60 dias. Se não for definido, será de 30 dias por padrão. Para saber mais, confira a diretiva de idade máxima.
• Adiciona example.com à lista de hosts a serem excluídos.

UseHsts exclui os seguintes hosts de loopback:

• localhost : o endereço de loopback IPv4.
• 127.0.0.1 : o endereço de loopback IPv4.
• [::1] : o endereço de loopback IPv6.

Recusar HTTPS/HSTS na criação do projeto

Em alguns cenários de serviço de back-end em que a segurança da conexão é tratada na borda voltada para o público da rede, a configuração da segurança de conexão em cada nó não é necessária. Os aplicativos Web gerados com base nos modelos no Visual Studio ou no comando dotnet new habilitam o redirecionamento para HTTPS e o HSTS. Para implantações que não exigem esses cenários, você pode recusar o HTTPS/HSTS quando o aplicativo é criado com base no modelo.

Para recusar HTTPS/HSTS:

dotnet new webapp --no-https

Confiar no certificado de desenvolvimento HTTPS do ASP.NET Core no Windows e macOS

Para o navegador Firefox, consulte a próxima seção.

O SDK do .NET Core inclui um certificado de desenvolvimento HTTPS. O certificado é instalado como parte da experiência de primeira execução. Por exemplo, executar dotnet new webapp pela primeira vez produz uma variação da saída a seguir:

Installed an ASP.NET Core HTTPS development certificate.
To trust the certificate, run 'dotnet dev-certs https --trust'
Learn about HTTPS: https://aka.ms/dotnet-https

Instalar o SDK do .NET Core instala o certificado de desenvolvimento HTTPS do ASP.NET Core no repositório de certificados do usuário local. O certificado foi instalado, mas não é confiável. Para confiar no certificado, realize a etapa única a seguir para executar a ferramenta do dotnet dev-certs:

dotnet dev-certs https --trust

O comando a seguir fornece ajuda para a ferramenta dotnet dev-certs:

dotnet dev-certs https --help

Confiar no certificado HTTPS com o Firefox para evitar o erro SEC_ERROR_INADEQUATE_KEY_USAGE

O navegador Firefox usa seu próprio repositório de certificados e, portanto, não confia nos certificados de desenvolvedor IIS Express ou Kestrel.

Há duas abordagens para confiar no certificado HTTPS com o Firefox: criar um arquivo de política ou configurar com o navegador FireFox. A configuração com o navegador cria o arquivo de política, para que as duas abordagens sejam equivalentes.

Criar um arquivo de política para confiar no certificado HTTPS com o Firefox

Crie um arquivo de política (policies.json) em:

• Windows: %PROGRAMFILES%\Mozilla Firefox\distribution\
• Macos: Firefox.app/Contents/Resources/distribution
• Linux: consulte Confiar no certificado com o Firefox no Linux mais adiante neste artigo.

Adicione o seguinte JSON ao arquivo de política do Firefox:

{
  "policies": {
    "Certificates": {
      "ImportEnterpriseRoots": true
    }
  }
}

O arquivo de política mencionado faz com que o Firefox confie em certificados do repositório de certificados do Windows. A próxima seção fornece uma abordagem alternativa para criar o arquivo de política anterior usando o navegador Firefox.

Configurar a confiança do certificado HTTPS usando o navegador Firefox

Defina security.enterprise_roots.enabled = true usando as seguintes instruções:

1. Insira about:config no navegador Firefox.
2. Selecione Aceitar o Risco e Continuar se você aceitar o risco.
3. Selecione Mostrar Tudo.
4. Defina security.enterprise_roots.enabled = true.
5. Saia e reinicie o Firefox.

Para obter mais informações, consulte Configurando Autoridades de Certificação (ACs) no Firefox e o arquivo mozilla/policy-templates/README.

Como configurar um certificado de desenvolvedor para o Docker

Consulte este problema do GitHub.

Confiar no certificado HTTPS no Linux

O estabelecimento de confiança é específico da distribuição e do navegador. As seções a seguir fornecem instruções para algumas distribuições populares e os navegadores Chromium (Edge e Chrome) e para o Firefox.

O Ubuntu confia no certificado para comunicação serviço a serviço

1. Instale o OpenSSL 1.1.1h ou posterior. Consulte sua distribuição para obter instruções sobre como atualizar o OpenSSL.

2. Execute os seguintes comandos:

   dotnet dev-certs https
   sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM
   sudo update-ca-certificates
   

Os comandos anteriores:

• Verifique se o certificado de desenvolvedor do usuário atual foi criado.
• Exporta o certificado com permissões elevadas necessárias para a pasta ca-certificates, usando o ambiente do usuário atual.
• Remova o sinalizador -E para exportar o certificado do usuário raiz, gerando-o, se necessário. Cada certificado recém-gerado tem uma impressão digital diferente. Ao executar como raiz, sudo e -E não são necessários.

O caminho no comando anterior é específico para o Ubuntu. Para outras distribuições, selecione um caminho apropriado ou use o caminho para as Autoridades de Certificação (ACs).

Confiar no certificado HTTPS no Linux usando o Edge ou o Chrome

Para navegadores Chromium no Linux:

• Instale o libnss3-tools para sua distribuição.

• Crie ou verifique se a pasta $HOME/.pki/nssdb existe no computador.

• Exporte o certificado com o seguinte comando:

  dotnet dev-certs https
  sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM
  

  O caminho no comando anterior é específico para o Ubuntu. Para outras distribuições, selecione um caminho apropriado ou use o caminho para as Autoridades de Certificação (ACs).

• Execute os seguintes comandos:

  certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n localhost -i /usr/local/share/ca-certificates/aspnet/https.crt
  

• Saia e reinicie o navegador.

Confiar no certificado com o Firefox no Linux

• Exporte o certificado com o seguinte comando:

  dotnet dev-certs https
  sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM
  

  O caminho no comando anterior é específico para o Ubuntu. Para outras distribuições, selecione um caminho apropriado ou use o caminho para as Autoridades de Certificação (ACs).

• Crie um arquivo JSON em /usr/lib/firefox/distribution/policies.json com o seguinte conteúdo:

cat <<EOF | sudo tee /usr/lib/firefox/distribution/policies.json
{
    "policies": {
        "Certificates": {
            "Install": [
                "/usr/local/share/ca-certificates/aspnet/https.crt"
            ]
        }
    }
}
EOF

Consulte Configurar a confiança do certificado HTTPS usando o navegador Firefox neste artigo para obter uma maneira alternativa de configurar o arquivo de política usando o navegador.

Confiar no certificado com Fedora 34

Firefox no Fedora

echo 'pref("general.config.filename", "firefox.cfg");
pref("general.config.obscure_value", 0);' > ./autoconfig.js

echo '//Enable policies.json
lockPref("browser.policies.perUserDir", false);' > firefox.cfg

echo "{
    \"policies\": {
        \"Certificates\": {
            \"Install\": [
                \"aspnetcore-localhost-https.crt\"
            ]
        }
    }
}" > policies.json

dotnet dev-certs https -ep localhost.crt --format PEM

sudo mv autoconfig.js /usr/lib64/firefox/
sudo mv firefox.cfg /usr/lib64/firefox/
sudo mv policies.json /usr/lib64/firefox/distribution/
mkdir -p ~/.mozilla/certificates
cp localhost.crt ~/.mozilla/certificates/aspnetcore-localhost-https.crt
rm localhost.crt

Confiar no dotnet-to-dotnet no Fedora

sudo cp localhost.crt /etc/pki/tls/certs/localhost.pem
sudo update-ca-trust
rm localhost.crt

Consulte este comentário do GitHub para obter mais informações.

Confiar no certificado com outras distribuições

Consulte este problema do GitHub.

Confiar no certificado HTTPS do Subsistema do Windows para Linux

O WSL (Subsistema do Windows para Linux) gera um certificado de desenvolvimento autoassinado HTTPS. Para configurar o repositório de certificados do Windows para confiar no certificado WSL:

• Exporte o certificado de desenvolvedor para um arquivo no Windows:

  dotnet dev-certs https -ep C:\<<path-to-folder>>\aspnetcore.pfx -p $CREDENTIAL_PLACEHOLDER$
  

  Em que $CREDENTIAL_PLACEHOLDER$ é uma senha.

• Em uma janela WSL, importe o certificado exportado na instância do WSL:

  dotnet dev-certs https --clean --import /mnt/c/<<path-to-folder>>/aspnetcore.pfx -p $CREDENTIAL_PLACEHOLDER$
  

A abordagem anterior é uma operação única por certificado e por distribuição WSL. É mais fácil do que exportar o certificado repetidas vezes. Se você atualizar ou regenerar o certificado no Windows, talvez seja necessário executar os comandos anteriores novamente.

Solucionar problemas de certificado, como certificado não confiável

Esta seção fornece ajuda quando o certificado de desenvolvimento HTTPS do ASP.NET Core foi instalado e é confiável, mas você ainda tem avisos do navegador de que o certificado não é confiável. O certificado de desenvolvimento HTTPS do ASP.NET Core é usado por Kestrel.

Para reparar o certificado IIS Express, consulte esse problema do Stackoverflow.

Todas as plataformas – certificado não confiável

Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo. A confiança do certificado é armazenada em cache por navegadores.

Falha em dotnet dev-certs https --clean

Os comandos anteriores resolvem a maioria dos problemas de confiança do navegador. Se o navegador ainda não estiver confiando no certificado, siga as sugestões específicas da plataforma a seguir.

Docker – certificado não confiável

• Exclua a pasta C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
• Limpe a solução. Exclua as pastas bin e obj.
• Reinicie a ferramenta de desenvolvimento. Por exemplo, Visual Studio, Visual Studio Code ou Visual Studio para Mac.

Windows – certificado não confiável

• Verifique os certificados no repositório de certificados. Deve haver um certificado localhost com o nome amigável ASP.NET Core HTTPS development certificate em Current User > Personal > Certificates e Current User > Trusted root certification authorities > Certificates
• Remova todos os certificados encontrados das autoridades de certificação raiz pessoais e confiáveis. Não remova o certificado localhost do IIS Express.
• Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo. A confiança do certificado é armazenada em cache por navegadores.

OS X – certificado não confiável

• Abra o Acesso ao Conjunto de Chaves.
• Selecione o conjunto de chaves do sistema.
• Verifique a presença de um certificado localhost.
• Verifique se ele contém um símbolo + no ícone para indicar que ele é confiável para todos os usuários.
• Remova o certificado do conjunto de chaves do sistema.
• Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo. A confiança do certificado é armazenada em cache por navegadores.

Consulte Erro HTTPS usando IIS Express (dotnet/AspNetCore #16892) para solucionar problemas de certificado com o Visual Studio.

Certificado do Linux não confiável

Verifique se o certificado que está sendo configurado para confiança é o certificado de desenvolvedor HTTPS do usuário que será usado pelo servidor Kestrel.

Verifique o certificado Kestrel de desenvolvedor HTTPS padrão do usuário atual no seguinte local:

ls -la ~/.dotnet/corefx/cryptography/x509stores/my

O arquivo de certificado Kestrel de desenvolvedor HTTPS é a impressão digital SHA1. Quando o arquivo é excluído via dotnet dev-certs https --clean, ele é regenerado quando necessário com uma impressão digital diferente. Verifique se a impressão digital do certificado exportado corresponde ao seguinte comando:

openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt

Se o certificado não corresponder, ele poderá ser um dos seguintes:

• Um certificado antigo.
• Um certificado de desenvolvedor exportado para o usuário raiz. Nesse caso, exporte o certificado.

O certificado do usuário raiz pode ser verificado em:

ls -la /root/.dotnet/corefx/cryptography/x509stores/my

Certificado SSL do IIS Express usado com o Visual Studio

Para corrigir problemas com o certificado do IIS Express, selecione Reparar no instalador do Visual Studio. Saiba mais neste tópico do GitHub.

Informações adicionais

• Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga
• Host ASP.NET Core no Linux com Nginx: configuração HTTPS
• Como configurar o SSL no IIS
• Suporte ao navegador HSTS do OWASP
• dotnet dev-certs

O redirecionamento HTTP para HTTPS causa ERR_INVALID_REDIRECT na solicitação de simulação do CORS

Solicitações para um ponto de extremidade usando HTTP que são redirecionadas para HTTPS por falha de UseHttpsRedirection com ERR_INVALID_REDIRECT na solicitação de simulação CORS.

Os projetos de API podem rejeitar solicitações HTTP em vez de usar UseHttpsRedirection para redirecionar solicitações para HTTPS.

Exigir HTTPS

Recomendamos que os aplicativos Web do ASP.NET Core de produção usem:

• Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) para redirecionar as solicitações HTTP para HTTPS.
• Middleware HSTS (UseHsts) para enviar cabeçalhos HSTS (Protocolo de Segurança do Transporte Estrito HTTP) para clientes.

UseHttpsRedirection

O seguinte código chama UseHttpsRedirection no arquivo Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

O código destacado anterior:

• Usa o padrão HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
• Usa o padrão HttpsRedirectionOptions.HttpsPort (nulo), a menos que seja substituído pela variável de ambiente ASPNETCORE_HTTPS_PORT ou IServerAddressesFeature.

É recomendável usar redirecionamentos temporários em vez de redirecionamentos permanentes. O cache de link pode causar um comportamento instável em ambientes de desenvolvimento. Se você preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente diferenteDevelopment , consulte a seção Configurar redirecionamentos permanentes na seção de produção . É recomendável usar o HSTS para sinalizar aos clientes que apenas solicitações de recursos seguras devem ser enviadas para o aplicativo (somente em produção).

Configuração da porta

Uma porta deve estar disponível para o middleware redirecionar uma solicitação insegura para HTTPS. Se nenhuma porta estiver disponível:

• O redirecionamento para HTTPS não ocorrerá.
• O middleware registrará o aviso "Falha ao determinar a porta https para redirecionamento".

Especifique a porta HTTPS usando qualquer uma das seguintes abordagens:

• Defina HttpsRedirectionOptions.HttpsPort.

• Defina a https_portconfiguração do host:

  • Na configuração do host.

  • Definindo a variável de ambiente ASPNETCORE_HTTPS_PORT.

  • Adicionando uma entrada de nível superior em appsettings.json:

    {
      "https_port": 443,
      "Logging": {
        "LogLevel": {
          "Default": "Information",
          "Microsoft.AspNetCore": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    

• Indique uma porta com o esquema seguro usando a variável de ambiente ASPNETCORE_URLS. A variável de ambiente configura o servidor. O middleware descobre indiretamente a porta HTTPS via IServerAddressesFeature. Essa abordagem não funciona em implantações de proxy reverso.

• Os modelos Web do ASP.NET Core definem uma URL HTTPS em Properties/launchsettings.json para Kestrel e para o IIS Express. launchsettings.json é usado apenas no computador local.

• Configure um ponto de extremidade de URL HTTPS para uma implantação de borda voltada para o público de um servidor Kestrel ou de um servidor HTTP.sys. Apenas uma porta HTTPS é usada pelo aplicativo. O middleware descobre a porta via IServerAddressesFeature.

Implantações em Edge

Quando Kestrel ou HTTP.sys é usado como um servidor de borda voltado para o público, Kestrel ou HTTP.sys deve ser configurado para escutar em ambos:

• A porta segura em que o cliente é redirecionado (normalmente, 443 em produção e 5001 em desenvolvimento).
• A porta insegura (normalmente, 80 em produção e 5000 em desenvolvimento).

A porta insegura deve ser acessível ao cliente para que o aplicativo receba uma solicitação insegura e redirecione o cliente para a porta segura.

Para obter mais informações, consulte a Kestrel ou a implementação do servidor Web HTTP.sys no ASP.NET Core.

Cenários de implantação

Qualquer firewall entre o cliente e o servidor também deve ter portas de comunicação abertas para tráfego.

Se as solicitações forem encaminhadas em uma configuração de proxy reverso, use Middleware de Cabeçalhos Encaminhados antes de chamar o Middleware de Redirecionamento para HTTPS. O Middleware de Cabeçalhos Encaminhados atualiza o Request.Scheme, usando o cabeçalho X-Forwarded-Proto. O middleware permite que os URIs de redirecionamento e outras políticas de segurança funcionem corretamente. Quando o Middleware de Cabeçalhos Encaminhados não é usado, o aplicativo de back-end pode não receber o esquema correto e acabar em um loop de redirecionamento. Uma mensagem de erro comum ao usuário final é que ocorreram muitos redirecionamentos.

Ao implantar no Serviço de Aplicativo do Azure, siga as diretrizes no Tutorial: Associar um certificado SSL personalizado existente aos Aplicativos Web do Azure.

Opções

O código realçado a seguir chama AddHttpsRedirection para configurar opções de middleware:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddHsts(options =>
{
    options.Preload = true;
    options.IncludeSubDomains = true;
    options.MaxAge = TimeSpan.FromDays(60);
    options.ExcludedHosts.Add("example.com");
    options.ExcludedHosts.Add("www.example.com");
});

builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = Status307TemporaryRedirect;
    options.HttpsPort = 5001;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Só é necessário chamar AddHttpsRedirection para alterar os valores de HttpsPort ou RedirectStatusCode.

O código destacado anterior:

• Define HttpsRedirectionOptions.RedirectStatusCode como Status307TemporaryRedirect, que é o valor padrão. Use os campos da classe StatusCodes para atribuições a RedirectStatusCode.
• Define a porta HTTPS como 5001.

Configurar redirecionamentos permanentes na produção

O middleware tem como padrão o envio de um Status307TemporaryRedirect com todos os redirecionamentos. Se preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente que não seja Development, envolva a configuração das opções do middleware em uma verificação condicional para um ambiente que não seja Development.

Ao configurar serviços em Program.cs:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

if (!builder.Environment.IsDevelopment())
{
    builder.Services.AddHttpsRedirection(options =>
    {
        options.RedirectStatusCode = Status308PermanentRedirect;
        options.HttpsPort = 443;
    });
}

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");

    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Abordagem alternativa do Middleware de Redirecionamento para HTTPS

Uma alternativa ao uso do Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) é usar o Middleware de Regravação de URL (AddRedirectToHttps). AddRedirectToHttps também pode definir o código de status e a porta quando o redirecionamento é executado. Para obter mais informações, consulte Middleware de Regravação de URL.

Ao redirecionar para HTTPS sem a necessidade de regras de redirecionamento adicionais, é recomendável usar o Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) descrito nesse artigo.

HSTS (Protocolo de Segurança do Transporte Estrito HTTP)

De acordo com o OWASP, o HSTS (Segurança do Transporte Estrito HTTP é um aperfeiçoamento de segurança opcional, que é especificado por um aplicativo Web por meio de um cabeçalho de resposta. Quando um navegador que dá suporte ao HSTS recebe esse cabeçalho:

• O navegador armazena a configuração para o domínio que impede o envio de qualquer comunicação por HTTP. O navegador força todas as comunicações via HTTPS.
• O navegador impede que o usuário use certificados não confiáveis ou inválidos. O navegador desabilita prompts que permitem que um usuário confie temporariamente nesse certificado.

Como o HSTS é imposto pelo cliente, ele tem algumas limitações:

• O cliente deve dar suporte ao HSTS.
• O HSTS requer pelo menos uma solicitação HTTPS bem-sucedida para estabelecer a política HSTS.
• O aplicativo deve verificar cada solicitação HTTP e redirecioná-la ou rejeitá-la.

O ASP.NET Core implementa o HSTS com o método de extensão UseHsts. O código a seguir chama UseHsts quando o aplicativo não está no modo de desenvolvimento:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

UseHsts não é recomendado no desenvolvimento porque as configurações do HSTS são altamente armazenáveis em cache por navegadores. Por padrão, UseHsts exclui o endereço de loopback local.

Para ambientes de produção que estão implementando HTTPS pela primeira vez, defina o HstsOptions.MaxAge inicial como um valor pequeno usando um dos métodos TimeSpan. Defina o valor de horas para não mais do que um único dia, caso precise reverter a infraestrutura HTTPS para HTTP. Depois de ter certeza da sustentabilidade da configuração HTTPS, aumente o valor max-age do HSTS; um valor comumente usado é um ano.

O seguinte código realçado:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddHsts(options =>
{
    options.Preload = true;
    options.IncludeSubDomains = true;
    options.MaxAge = TimeSpan.FromDays(60);
    options.ExcludedHosts.Add("example.com");
    options.ExcludedHosts.Add("www.example.com");
});

builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = Status307TemporaryRedirect;
    options.HttpsPort = 5001;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

• Define o parâmetro de pré-carregamento do cabeçalho Strict-Transport-Security. O preload não faz parte da especificação RFC HSTS, mas é suportado por navegadores para pré-carregar sites HSTS em uma nova instalação. Para obter mais informações, consulte https://hstspreload.org/.
• Habilita includeSubDomain, que aplica a política do HSTS aos subdomínios do Host.
• Define explicitamente o parâmetro max-age do cabeçalho Strict-Transport-Security como 60 dias. Se não for definido, será de 30 dias por padrão. Para saber mais, confira a diretiva de idade máxima.
• Adiciona example.com à lista de hosts a serem excluídos.

UseHsts exclui os seguintes hosts de loopback:

• localhost : o endereço de loopback IPv4.
• 127.0.0.1 : o endereço de loopback IPv4.
• [::1] : o endereço de loopback IPv6.

Recusar HTTPS/HSTS na criação do projeto

Em alguns cenários de serviço de back-end em que a segurança da conexão é tratada na borda voltada para o público da rede, a configuração da segurança de conexão em cada nó não é necessária. Os aplicativos Web gerados com base nos modelos no Visual Studio ou no comando dotnet new habilitam o redirecionamento para HTTPS e o HSTS. Para implantações que não exigem esses cenários, você pode recusar o HTTPS/HSTS quando o aplicativo é criado com base no modelo.

Para recusar HTTPS/HSTS:

dotnet new webapp --no-https

Confiar no certificado de desenvolvimento HTTPS do ASP.NET Core no Windows e macOS

Para o navegador Firefox, consulte a próxima seção.

O SDK do .NET Core inclui um certificado de desenvolvimento HTTPS. O certificado é instalado como parte da experiência de primeira execução. Por exemplo, dotnet --info produz uma variação da saída a seguir:

ASP.NET Core
------------
Successfully installed the ASP.NET Core HTTPS Development Certificate.
To trust the certificate run 'dotnet dev-certs https --trust' (Windows and macOS only).
For establishing trust on other platforms refer to the platform specific documentation.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.

Instalar o SDK do .NET Core instala o certificado de desenvolvimento HTTPS do ASP.NET Core no repositório de certificados do usuário local. O certificado foi instalado, mas não é confiável. Para confiar no certificado, realize a etapa única a seguir para executar a ferramenta do dotnet dev-certs:

dotnet dev-certs https --trust

O comando a seguir fornece ajuda para a ferramenta dotnet dev-certs:

dotnet dev-certs https --help

Confiar no certificado HTTPS com o Firefox para evitar o erro SEC_ERROR_INADEQUATE_KEY_USAGE

O navegador Firefox usa seu próprio repositório de certificados e, portanto, não confia nos certificados de desenvolvedor IIS Express ou Kestrel.

Há duas abordagens para confiar no certificado HTTPS com o Firefox: criar um arquivo de política ou configurar com o navegador FireFox. A configuração com o navegador cria o arquivo de política, para que as duas abordagens sejam equivalentes.

Criar um arquivo de política para confiar no certificado HTTPS com o Firefox

Crie um arquivo de política (policies.json) em:

• Windows: %PROGRAMFILES%\Mozilla Firefox\distribution\
• Macos: Firefox.app/Contents/Resources/distribution
• Linux: veja Confiar no certificado com o Firefox no Linux neste artigo.

Adicione o seguinte JSON ao arquivo de política do Firefox:

{
  "policies": {
    "Certificates": {
      "ImportEnterpriseRoots": true
    }
  }
}

O arquivo de política mencionado faz com que o Firefox confie em certificados do repositório de certificados do Windows. A próxima seção fornece uma abordagem alternativa para criar o arquivo de política anterior usando o navegador Firefox.

Configurar a confiança do certificado HTTPS usando o navegador Firefox

Defina security.enterprise_roots.enabled = true usando as seguintes instruções:

1. Insira about:config no navegador Firefox.
2. Selecione Aceitar o Risco e Continuar se você aceitar o risco.
3. Selecione Mostrar Tudo
4. Defina security.enterprise_roots.enabled = true
5. Saia e reinicie o Firefox

Para obter mais informações, consulte Configurando Autoridades de Certificação (ACs) no Firefox e o arquivo mozilla/policy-templates/README.

Como configurar um certificado de desenvolvedor para o Docker

Consulte este problema do GitHub.

Confiar no certificado HTTPS no Linux

O estabelecimento de confiança é específico da distribuição e do navegador. As seções a seguir fornecem instruções para algumas distribuições populares e os navegadores Chromium (Edge e Chrome) e para o Firefox.

O Ubuntu confia no certificado para comunicação serviço a serviço

As instruções a seguir não funcionam para algumas versões do Ubuntu, como a 20.04. Para obter mais informações, consulte o problema dotnet/AspNetCore.Docs #23686 do GitHub.

1. Instale o OpenSSL 1.1.1h ou posterior. Consulte sua distribuição para obter instruções sobre como atualizar o OpenSSL.

2. Execute os seguintes comandos:

   dotnet dev-certs https
   sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM
   sudo update-ca-certificates
   

Os comandos anteriores:

• Verifique se o certificado de desenvolvedor do usuário atual foi criado.
• Exporta o certificado com permissões elevadas necessárias para a pasta ca-certificates, usando o ambiente do usuário atual.
• A remoção do sinalizador -E exporta o certificado do usuário raiz, gerando-o, se necessário. Cada certificado recém-gerado tem uma impressão digital diferente. Ao executar como raiz, sudo e -E não são necessários.

O caminho no comando anterior é específico para o Ubuntu. Para outras distribuições, selecione um caminho apropriado ou use o caminho para as Autoridades de Certificação (ACs).

Confiar no certificado HTTPS no Linux usando o Edge ou o Chrome

cat <<EOF | sudo tee /usr/lib/firefox/distribution/policies.json
{
    "policies": {
        "Certificates": {
            "Install": [
                "/usr/local/share/ca-certificates/aspnet/https.crt"
            ]
        }
    }
}
EOF

dnf install nss-tools

cd ${ProjectDirectory}
dotnet dev-certs https -ep ${ProjectDirectory}/${CertificateName}.crt --format PEM

certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt

certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "P,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt

alias curl="curl --cacert ${ProjectDirectory}/${CertificateName}.crt"

certutil -d sql:$HOME/.pki/nssdb -D -n ${CertificateName}
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -D -n ${CertificateName}
rm ${ProjectDirectory}/${CertificateName}.crt
dotnet dev-certs https --clean

Confiar no certificado com Fedora 34

See:

• Este comentário do GitHub
• Fedora: usando certificados de sistema compartilhados
• Configurar um ambiente de desenvolvimento do .NET no Fedora.

Confiar no certificado com outras distribuições

Consulte este problema do GitHub.

Confiar no certificado HTTPS do Subsistema do Windows para Linux

As instruções a seguir não funcionam para algumas distribuições do Linux, como o Ubuntu 20.04. Para obter mais informações, consulte o problema dotnet/AspNetCore.Docs #23686 do GitHub.

O WSL (Subsistema do Windows para Linux) gera um certificado de desenvolvimento autoassinado HTTPS, que por padrão não é confiável no Windows. A maneira mais fácil de fazer com que o Windows confie no certificado WSL é configurar o WSL para usar o mesmo certificado que o Windows:

• No Windows, exporte o certificado do desenvolvedor para um arquivo:

  dotnet dev-certs https -ep https.pfx -p $CREDENTIAL_PLACEHOLDER$ --trust
  

  Em que $CREDENTIAL_PLACEHOLDER$ é uma senha.

• Em uma janela WSL, importe o certificado exportado na instância do WSL:

  dotnet dev-certs https --clean --import <<path-to-pfx>> --password $CREDENTIAL_PLACEHOLDER$
  

A abordagem anterior é uma operação única por certificado e por distribuição WSL. É mais fácil do que exportar o certificado repetidas vezes. Se você atualizar ou regenerar o certificado no Windows, talvez seja necessário executar os comandos anteriores novamente.

Solucionar problemas de certificado, como certificado não confiável

Esta seção fornece ajuda quando o certificado de desenvolvimento HTTPS do ASP.NET Core foi instalado e é confiável, mas você ainda tem avisos do navegador de que o certificado não é confiável. O certificado de desenvolvimento HTTPS do ASP.NET Core é usado por Kestrel.

Para reparar o certificado IIS Express, consulte esse problema do Stackoverflow.

Todas as plataformas – certificado não confiável

Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo. A confiança do certificado é armazenada em cache por navegadores.

Falha em dotnet dev-certs https --clean

Os comandos anteriores resolvem a maioria dos problemas de confiança do navegador. Se o navegador ainda não estiver confiando no certificado, siga as sugestões específicas da plataforma a seguir.

Docker – certificado não confiável

• Exclua a pasta C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
• Limpe a solução. Exclua as pastas bin e obj.
• Reinicie a ferramenta de desenvolvimento. Por exemplo, o Visual Studio ou o Visual Studio Code.

Windows – certificado não confiável

• Verifique os certificados no repositório de certificados. Deve haver um certificado localhost com o nome amigável ASP.NET Core HTTPS development certificate em Current User > Personal > Certificates e Current User > Trusted root certification authorities > Certificates
• Remova todos os certificados encontrados das autoridades de certificação raiz pessoais e confiáveis. Não remova o certificado localhost do IIS Express.
• Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo.

OS X – certificado não confiável

• Abra o Acesso ao Conjunto de Chaves.
• Selecione o conjunto de chaves do sistema.
• Verifique a presença de um certificado localhost.
• Verifique se ele contém um símbolo + no ícone para indicar que ele é confiável para todos os usuários.
• Remova o certificado do conjunto de chaves do sistema.
• Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo.

Consulte Erro HTTPS usando IIS Express (dotnet/AspNetCore #16892) para solucionar problemas de certificado com o Visual Studio.

Certificado do Linux não confiável

Verifique se o certificado que está sendo configurado para confiança é o certificado de desenvolvedor HTTPS do usuário que será usado pelo servidor Kestrel.

Verifique o certificado Kestrel de desenvolvedor HTTPS padrão do usuário atual no seguinte local:

ls -la ~/.dotnet/corefx/cryptography/x509stores/my

O arquivo de certificado Kestrel de desenvolvedor HTTPS é a impressão digital SHA1. Quando o arquivo é excluído via dotnet dev-certs https --clean, ele é regenerado quando necessário com uma impressão digital diferente. Verifique se a impressão digital do certificado exportado corresponde ao seguinte comando:

openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt

Se o certificado não corresponder, ele poderá ser um dos seguintes:

• Um certificado antigo.
• Um certificado de desenvolvedor exportado para o usuário raiz. Nesse caso, exporte o certificado.

O certificado do usuário raiz pode ser verificado em:

ls -la /root/.dotnet/corefx/cryptography/x509stores/my

Certificado SSL do IIS Express usado com o Visual Studio

Para corrigir problemas com o certificado do IIS Express, selecione Reparar no instalador do Visual Studio. Saiba mais neste tópico do GitHub.

A política de grupo impede que certificados autoassinados sejam confiáveis

Em alguns casos, a política de grupo pode impedir que certificados autoassinados sejam confiáveis. Saiba mais neste tópico do GitHub.

Informações adicionais

• Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga
• Host ASP.NET Core no Linux com Nginx: configuração HTTPS
• Como configurar o SSL no IIS
• Configurar pontos de extremidade para o Kestrel servidor Web
• Suporte ao navegador HSTS do OWASP

O redirecionamento HTTP para HTTPS causa ERR_INVALID_REDIRECT na solicitação de simulação do CORS

Solicitações para um ponto de extremidade usando HTTP que são redirecionadas para HTTPS por falha de UseHttpsRedirection com ERR_INVALID_REDIRECT na solicitação de simulação CORS.

Os projetos de API podem rejeitar solicitações HTTP em vez de usar UseHttpsRedirection para redirecionar solicitações para HTTPS.

Exigir HTTPS

Recomendamos que os aplicativos Web do ASP.NET Core de produção usem:

• Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) para redirecionar as solicitações HTTP para HTTPS.
• Middleware HSTS (UseHsts) para enviar cabeçalhos HSTS (Protocolo de Segurança do Transporte Estrito HTTP) para clientes.

UseHttpsRedirection

O seguinte código chama UseHttpsRedirection no arquivo Program.cs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

O código destacado anterior:

• Usa o padrão HttpsRedirectionOptions.RedirectStatusCode (Status307TemporaryRedirect).
• Usa o padrão HttpsRedirectionOptions.HttpsPort (nulo), a menos que seja substituído pela variável de ambiente ASPNETCORE_HTTPS_PORT ou IServerAddressesFeature.

É recomendável usar redirecionamentos temporários em vez de redirecionamentos permanentes. O cache de link pode causar um comportamento instável em ambientes de desenvolvimento. Se você preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente diferenteDevelopment , consulte a seção Configurar redirecionamentos permanentes na seção de produção . É recomendável usar o HSTS para sinalizar aos clientes que apenas solicitações de recursos seguras devem ser enviadas para o aplicativo (somente em produção).

Configuração da porta

Uma porta deve estar disponível para o middleware redirecionar uma solicitação insegura para HTTPS. Se nenhuma porta estiver disponível:

• O redirecionamento para HTTPS não ocorrerá.
• O middleware registrará o aviso "Falha ao determinar a porta https para redirecionamento".

Especifique a porta HTTPS usando qualquer uma das seguintes abordagens:

• Defina HttpsRedirectionOptions.HttpsPort.

• Defina a https_portconfiguração do host:

  • Na configuração do host.

  • Definindo a variável de ambiente ASPNETCORE_HTTPS_PORT.

  • Adicionando uma entrada de nível superior em appsettings.json:

    {
      "https_port": 443,
      "Logging": {
        "LogLevel": {
          "Default": "Information",
          "Microsoft.AspNetCore": "Warning"
        }
      },
      "AllowedHosts": "*"
    }
    

• Indique uma porta com o esquema seguro usando a variável de ambiente ASPNETCORE_URLS. A variável de ambiente configura o servidor. O middleware descobre indiretamente a porta HTTPS via IServerAddressesFeature. Essa abordagem não funciona em implantações de proxy reverso.

• Os modelos Web do ASP.NET Core definem uma URL HTTPS em Properties/launchsettings.json para Kestrel e para o IIS Express. launchsettings.json é usado apenas no computador local.

• Configure um ponto de extremidade de URL HTTPS para uma implantação de borda voltada para o público de um servidor Kestrel ou de um servidor HTTP.sys. Apenas uma porta HTTPS é usada pelo aplicativo. O middleware descobre a porta via IServerAddressesFeature.

Implantações em Edge

Quando Kestrel ou HTTP.sys é usado como um servidor de borda voltado para o público, Kestrel ou HTTP.sys deve ser configurado para escutar em ambos:

• A porta segura em que o cliente é redirecionado (normalmente, 443 em produção e 5001 em desenvolvimento).
• A porta insegura (normalmente, 80 em produção e 5000 em desenvolvimento).

A porta insegura deve ser acessível ao cliente para que o aplicativo receba uma solicitação insegura e redirecione o cliente para a porta segura.

Para obter mais informações, consulte a Kestrel ou a implementação do servidor Web HTTP.sys no ASP.NET Core.

Cenários de implantação

Qualquer firewall entre o cliente e o servidor também deve ter portas de comunicação abertas para tráfego.

Se as solicitações forem encaminhadas em uma configuração de proxy reverso, use Middleware de Cabeçalhos Encaminhados antes de chamar o Middleware de Redirecionamento para HTTPS. O Middleware de Cabeçalhos Encaminhados atualiza o Request.Scheme, usando o cabeçalho X-Forwarded-Proto. O middleware permite que os URIs de redirecionamento e outras políticas de segurança funcionem corretamente. Quando o Middleware de Cabeçalhos Encaminhados não é usado, o aplicativo de back-end pode não receber o esquema correto e acabar em um loop de redirecionamento. Uma mensagem de erro comum ao usuário final é que ocorreram muitos redirecionamentos.

Ao implantar no Serviço de Aplicativo do Azure, siga as diretrizes no Tutorial: Associar um certificado SSL personalizado existente aos Aplicativos Web do Azure.

Opções

O código realçado a seguir chama AddHttpsRedirection para configurar opções de middleware:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddHsts(options =>
{
    options.Preload = true;
    options.IncludeSubDomains = true;
    options.MaxAge = TimeSpan.FromDays(60);
    options.ExcludedHosts.Add("example.com");
    options.ExcludedHosts.Add("www.example.com");
});

builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = Status307TemporaryRedirect;
    options.HttpsPort = 5001;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Só é necessário chamar AddHttpsRedirection para alterar os valores de HttpsPort ou RedirectStatusCode.

O código destacado anterior:

• Define HttpsRedirectionOptions.RedirectStatusCode como Status307TemporaryRedirect, que é o valor padrão. Use os campos da classe StatusCodes para atribuições a RedirectStatusCode.
• Define a porta HTTPS como 5001.

Configurar redirecionamentos permanentes na produção

O middleware tem como padrão o envio de um Status307TemporaryRedirect com todos os redirecionamentos. Se preferir enviar um código de status de redirecionamento permanente quando o aplicativo estiver em um ambiente que não seja Development, envolva a configuração das opções do middleware em uma verificação condicional para um ambiente que não seja Development.

Ao configurar serviços em Program.cs:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

if (!builder.Environment.IsDevelopment())
{
    builder.Services.AddHttpsRedirection(options =>
    {
        options.RedirectStatusCode = Status308PermanentRedirect;
        options.HttpsPort = 443;
    });
}

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");

    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

Abordagem alternativa do Middleware de Redirecionamento para HTTPS

Uma alternativa ao uso do Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) é usar o Middleware de Regravação de URL (AddRedirectToHttps). AddRedirectToHttps também pode definir o código de status e a porta quando o redirecionamento é executado. Para obter mais informações, consulte Middleware de Regravação de URL.

Ao redirecionar para HTTPS sem a necessidade de regras de redirecionamento adicionais, é recomendável usar o Middleware de Redirecionamento para HTTPS (UseHttpsRedirection) descrito nesse artigo.

HSTS (Protocolo de Segurança do Transporte Estrito HTTP)

De acordo com o OWASP, o HSTS (Segurança do Transporte Estrito HTTP é um aperfeiçoamento de segurança opcional, que é especificado por um aplicativo Web por meio de um cabeçalho de resposta. Quando um navegador que dá suporte ao HSTS recebe esse cabeçalho:

• O navegador armazena a configuração para o domínio que impede o envio de qualquer comunicação por HTTP. O navegador força todas as comunicações via HTTPS.
• O navegador impede que o usuário use certificados não confiáveis ou inválidos. O navegador desabilita prompts que permitem que um usuário confie temporariamente nesse certificado.

Como o HSTS é imposto pelo cliente, ele tem algumas limitações:

• O cliente deve dar suporte ao HSTS.
• O HSTS requer pelo menos uma solicitação HTTPS bem-sucedida para estabelecer a política HSTS.
• O aplicativo deve verificar cada solicitação HTTP e redirecioná-la ou rejeitá-la.

O ASP.NET Core implementa o HSTS com o método de extensão UseHsts. O código a seguir chama UseHsts quando o aplicativo não está no modo de desenvolvimento:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

UseHsts não é recomendado no desenvolvimento porque as configurações do HSTS são altamente armazenáveis em cache por navegadores. Por padrão, UseHsts exclui o endereço de loopback local.

Para ambientes de produção que estão implementando HTTPS pela primeira vez, defina o HstsOptions.MaxAge inicial como um valor pequeno usando um dos métodos TimeSpan. Defina o valor de horas para não mais do que um único dia, caso precise reverter a infraestrutura HTTPS para HTTP. Depois de ter certeza da sustentabilidade da configuração HTTPS, aumente o valor max-age do HSTS; um valor comumente usado é um ano.

O seguinte código realçado:

using static Microsoft.AspNetCore.Http.StatusCodes;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();

builder.Services.AddHsts(options =>
{
    options.Preload = true;
    options.IncludeSubDomains = true;
    options.MaxAge = TimeSpan.FromDays(60);
    options.ExcludedHosts.Add("example.com");
    options.ExcludedHosts.Add("www.example.com");
});

builder.Services.AddHttpsRedirection(options =>
{
    options.RedirectStatusCode = Status307TemporaryRedirect;
    options.HttpsPort = 5001;
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();

app.Run();

• Define o parâmetro de pré-carregamento do cabeçalho Strict-Transport-Security. O preload não faz parte da especificação RFC HSTS, mas é suportado por navegadores para pré-carregar sites HSTS em uma nova instalação. Para obter mais informações, consulte https://hstspreload.org/.
• Habilita includeSubDomain, que aplica a política do HSTS aos subdomínios do Host.
• Define explicitamente o parâmetro max-age do cabeçalho Strict-Transport-Security como 60 dias. Se não for definido, será de 30 dias por padrão. Para saber mais, confira a diretiva de idade máxima.
• Adiciona example.com à lista de hosts a serem excluídos.

UseHsts exclui os seguintes hosts de loopback:

• localhost : o endereço de loopback IPv4.
• 127.0.0.1 : o endereço de loopback IPv4.
• [::1] : o endereço de loopback IPv6.

Recusar HTTPS/HSTS na criação do projeto

Em alguns cenários de serviço de back-end em que a segurança da conexão é tratada na borda voltada para o público da rede, a configuração da segurança de conexão em cada nó não é necessária. Os aplicativos Web gerados com base nos modelos no Visual Studio ou no comando dotnet new habilitam o redirecionamento para HTTPS e o HSTS. Para implantações que não exigem esses cenários, você pode recusar o HTTPS/HSTS quando o aplicativo é criado com base no modelo.

Para recusar HTTPS/HSTS:

dotnet new webapp --no-https

Confiar no certificado de desenvolvimento HTTPS do ASP.NET Core no Windows e macOS

Para o navegador Firefox, consulte a próxima seção.

O SDK do .NET inclui um certificado de desenvolvimento HTTPS. O certificado é instalado como parte da experiência de primeira execução. Por exemplo, dotnet --info produz uma variação da saída a seguir:

ASP.NET Core
------------
Successfully installed the ASP.NET Core HTTPS Development Certificate.
To trust the certificate run 'dotnet dev-certs https --trust' (Windows and macOS only).
For establishing trust on other platforms refer to the platform specific documentation.
For more information on configuring HTTPS see https://go.microsoft.com/fwlink/?linkid=848054.

A instalação do SDK do .NET instala o certificado de desenvolvimento HTTPS do ASP.NET Core no repositório de certificados do usuário local. O certificado foi instalado, mas não é confiável. Para confiar no certificado, realize a etapa única a seguir para executar a ferramenta do dotnet dev-certs:

dotnet dev-certs https --trust

O comando a seguir fornece ajuda para a ferramenta dotnet dev-certs:

dotnet dev-certs https --help

Confiar no certificado HTTPS com o Firefox para evitar o erro SEC_ERROR_INADEQUATE_KEY_USAGE

O navegador Firefox usa seu próprio repositório de certificados e, portanto, não confia nos certificados de desenvolvedor IIS Express ou Kestrel.

Há duas abordagens para confiar no certificado HTTPS com o Firefox: criar um arquivo de política ou configurar com o navegador FireFox. A configuração com o navegador cria o arquivo de política, para que as duas abordagens sejam equivalentes.

Criar um arquivo de política para confiar no certificado HTTPS com o Firefox

Crie um arquivo de política (policies.json) em:

• Windows: %PROGRAMFILES%\Mozilla Firefox\distribution\
• Macos: Firefox.app/Contents/Resources/distribution
• Linux: veja Confiar no certificado com o Firefox no Linux neste artigo.

Adicione o seguinte JSON ao arquivo de política do Firefox:

{
  "policies": {
    "Certificates": {
      "ImportEnterpriseRoots": true
    }
  }
}

O arquivo de política mencionado faz com que o Firefox confie em certificados do repositório de certificados do Windows. A próxima seção fornece uma abordagem alternativa para criar o arquivo de política anterior usando o navegador Firefox.

Configurar a confiança do certificado HTTPS usando o navegador Firefox

Defina security.enterprise_roots.enabled = true usando as seguintes instruções:

1. Insira about:config no navegador Firefox.
2. Selecione Aceitar o Risco e Continuar se você aceitar o risco.
3. Selecione Mostrar Tudo
4. Defina security.enterprise_roots.enabled = true
5. Saia e reinicie o Firefox

Para obter mais informações, consulte Configurando Autoridades de Certificação (ACs) no Firefox e o arquivo mozilla/policy-templates/README.

Como configurar um certificado de desenvolvedor para o Docker

Consulte este problema do GitHub.

Confiar no certificado HTTPS no Linux

O estabelecimento de confiança é específico da distribuição e do navegador. As seções a seguir fornecem instruções para algumas distribuições populares e os navegadores Chromium (Edge e Chrome) e para o Firefox.

Confiar no certificado HTTPS no Linux com linux-dev-certs

linux-dev-certs é uma ferramenta global .NET de software livre, com suporte para a comunidade, que fornece uma maneira conveniente de criar e confiar em um certificado de desenvolvedor no Linux. A ferramenta não é mantida nem tem suporte da Microsoft.

Os comandos a seguir instalam a ferramenta e criam um certificado de desenvolvedor confiável:

dotnet tool update -g linux-dev-certs
dotnet linux-dev-certs install

Para obter mais informações ou relatar problemas, consulte o repositório GitHub linux-dev-certs.

O Ubuntu confia no certificado para comunicação serviço a serviço

As instruções a seguir não funcionam para algumas versões do Ubuntu, como a 20.04. Para obter mais informações, consulte o problema dotnet/AspNetCore.Docs #23686 do GitHub.

1. Instale o OpenSSL 1.1.1h ou posterior. Consulte sua distribuição para obter instruções sobre como atualizar o OpenSSL.

2. Execute os seguintes comandos:

   dotnet dev-certs https
   sudo -E dotnet dev-certs https -ep /usr/local/share/ca-certificates/aspnet/https.crt --format PEM
   sudo update-ca-certificates
   

Os comandos anteriores:

• Verifique se o certificado de desenvolvedor do usuário atual foi criado.
• Exporta o certificado com permissões elevadas necessárias para a pasta ca-certificates, usando o ambiente do usuário atual.
• A remoção do sinalizador -E exporta o certificado do usuário raiz, gerando-o, se necessário. Cada certificado recém-gerado tem uma impressão digital diferente. Ao executar como raiz, sudo e -E não são necessários.

O caminho no comando anterior é específico para o Ubuntu. Para outras distribuições, selecione um caminho apropriado ou use o caminho para as Autoridades de Certificação (ACs).

Confiar no certificado HTTPS no Linux usando o Edge ou o Chrome

cat <<EOF | sudo tee /usr/lib/firefox/distribution/policies.json
{
    "policies": {
        "Certificates": {
            "Install": [
                "/usr/local/share/ca-certificates/aspnet/https.crt"
            ]
        }
    }
}
EOF

dnf install nss-tools

cd ${ProjectDirectory}
dotnet dev-certs https -ep ${ProjectDirectory}/${CertificateName}.crt --format PEM

certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt

certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "P,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -A -t "C,," -n ${CertificateName} -i ${ProjectDirectory}/${CertificateName}.crt

alias curl="curl --cacert ${ProjectDirectory}/${CertificateName}.crt"

certutil -d sql:$HOME/.pki/nssdb -D -n ${CertificateName}
certutil -d sql:$HOME/.mozilla/firefox/${UserProfile}/ -D -n ${CertificateName}
rm ${ProjectDirectory}/${CertificateName}.crt
dotnet dev-certs https --clean

Confiar no certificado com Fedora 34

See:

• Este comentário do GitHub
• Fedora: usando certificados de sistema compartilhados
• Configurar um ambiente de desenvolvimento do .NET no Fedora.

Confiar no certificado com outras distribuições

Consulte este problema do GitHub.

Confiar no certificado HTTPS do Subsistema do Windows para Linux

As instruções a seguir não funcionam para algumas distribuições do Linux, como o Ubuntu 20.04. Para obter mais informações, consulte o problema dotnet/AspNetCore.Docs #23686 do GitHub.

O WSL (Subsistema do Windows para Linux) gera um certificado de desenvolvimento autoassinado HTTPS, que por padrão não é confiável no Windows. A maneira mais fácil de fazer com que o Windows confie no certificado WSL é configurar o WSL para usar o mesmo certificado que o Windows:

• No Windows, exporte o certificado do desenvolvedor para um arquivo:

  dotnet dev-certs https -ep https.pfx -p $CREDENTIAL_PLACEHOLDER$ --trust
  

  Em que $CREDENTIAL_PLACEHOLDER$ é uma senha.

• Em uma janela WSL, importe o certificado exportado na instância do WSL:

  dotnet dev-certs https --clean --import <<path-to-pfx>> --password $CREDENTIAL_PLACEHOLDER$
  

A abordagem anterior é uma operação única por certificado e por distribuição WSL. É mais fácil do que exportar o certificado repetidas vezes. Se você atualizar ou regenerar o certificado no Windows, talvez seja necessário executar os comandos anteriores novamente.

Solucionar problemas de certificado, como certificado não confiável

Esta seção fornece ajuda quando o certificado de desenvolvimento HTTPS do ASP.NET Core foi instalado e é confiável, mas você ainda tem avisos do navegador de que o certificado não é confiável. O certificado de desenvolvimento HTTPS do ASP.NET Core é usado por Kestrel.

Para reparar o certificado IIS Express, consulte esse problema do Stackoverflow.

Todas as plataformas – certificado não confiável

Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo. A confiança do certificado é armazenada em cache por navegadores.

Falha em dotnet dev-certs https --clean

Os comandos anteriores resolvem a maioria dos problemas de confiança do navegador. Se o navegador ainda não estiver confiando no certificado, siga as sugestões específicas da plataforma a seguir.

Docker – certificado não confiável

• Exclua a pasta C:\Users{USER}\AppData\Roaming\ASP.NET\Https.
• Limpe a solução. Exclua as pastas bin e obj.
• Reinicie a ferramenta de desenvolvimento. Por exemplo, o Visual Studio ou o Visual Studio Code.

Windows – certificado não confiável

• Verifique os certificados no repositório de certificados. Deve haver um certificado localhost com o nome amigável ASP.NET Core HTTPS development certificate em Current User > Personal > Certificates e Current User > Trusted root certification authorities > Certificates
• Remova todos os certificados encontrados das autoridades de certificação raiz pessoais e confiáveis. Não remova o certificado localhost do IIS Express.
• Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo.

OS X – certificado não confiável

• Abra o Acesso ao Conjunto de Chaves.
• Selecione o conjunto de chaves do sistema.
• Verifique a presença de um certificado localhost.
• Verifique se ele contém um símbolo + no ícone para indicar que ele é confiável para todos os usuários.
• Remova o certificado do conjunto de chaves do sistema.
• Execute os seguintes comandos:

dotnet dev-certs https --clean
dotnet dev-certs https --trust

Feche todas as instâncias do navegador abertas. Abra uma nova janela do navegador para o aplicativo.

Consulte Erro HTTPS usando IIS Express (dotnet/AspNetCore #16892) para solucionar problemas de certificado com o Visual Studio.

Certificado do Linux não confiável

Verifique se o certificado que está sendo configurado para confiança é o certificado de desenvolvedor HTTPS do usuário que será usado pelo servidor Kestrel.

Verifique o certificado Kestrel de desenvolvedor HTTPS padrão do usuário atual no seguinte local:

ls -la ~/.dotnet/corefx/cryptography/x509stores/my

O arquivo de certificado Kestrel de desenvolvedor HTTPS é a impressão digital SHA1. Quando o arquivo é excluído via dotnet dev-certs https --clean, ele é regenerado quando necessário com uma impressão digital diferente. Verifique se a impressão digital do certificado exportado corresponde ao seguinte comando:

openssl x509 -noout -fingerprint -sha1 -inform pem -in /usr/local/share/ca-certificates/aspnet/https.crt

Se o certificado não corresponder, ele poderá ser um dos seguintes:

• Um certificado antigo.
• Um certificado de desenvolvedor exportado para o usuário raiz. Nesse caso, exporte o certificado.

O certificado do usuário raiz pode ser verificado em:

ls -la /root/.dotnet/corefx/cryptography/x509stores/my

Certificado SSL do IIS Express usado com o Visual Studio

Para corrigir problemas com o certificado do IIS Express, selecione Reparar no instalador do Visual Studio. Saiba mais neste tópico do GitHub.

A política de grupo impede que certificados autoassinados sejam confiáveis

Em alguns casos, a política de grupo pode impedir que certificados autoassinados sejam confiáveis. Saiba mais neste tópico do GitHub.

Informações adicionais

• Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga
• Host ASP.NET Core no Linux com Nginx: configuração HTTPS
• Como configurar o SSL no IIS
• Configurar pontos de extremidade para o Kestrel servidor Web
• Suporte ao navegador HSTS do OWASP