Forçar HTTPS no ASP.NET Core

Por David Galvan e Rick Anderson

Este artigo mostra como:

• Exigir HTTPS para todas as solicitações.
• Redirecionar todas as solicitações HTTP para HTTPS.

Nenhuma API pode impedir que um cliente envie dados confidenciais na primeira solicitação.

Advertência

Projetos API

Não usar RequireHttpsAttribute em APIs da Web que recebem informações confidenciais. RequireHttpsAttribute usa códigos de status HTTP para redirecionar navegadores de HTTP para HTTPS. Os clientes de API podem não entender ou obedecer redirecionamentos de HTTP para HTTPS. Esses clientes podem enviar informações por HTTP. As APIs da Web devem seguir uma das seguintes opções:

• Não escutar em HTTP.
• Feche a conexão com o código de status 400 (Solicitação incorreta) e não atenda a solicitação.

Para desabilitar o redirecionamento HTTP em uma API, defina a variável de ambiente ASPNETCORE_URLS ou use o sinalizador de linha de comando --urls. Para obter mais informações, consulte Usar vários ambientes no ASP.NET Core e 8 maneiras de definir as URLs de um aplicativo ASP.NET Core por Andrew Lock.

Projetos HSTS e API

Os projetos de API padrão não incluem HSTS porque HSTS geralmente é uma instrução apenas do navegador. Outros chamadores, como aplicativos de telefone ou desktop, não obedecem a instrução. Mesmo dentro de navegadores, uma única chamada autenticada para uma API sobre HTTP tem riscos em redes inseguras. A abordagem segura é configurar projetos de API para ouvir e responder somente por HTTPS.

O redirecionamento HTTP para HTTPS causa ERR_INVALID_REDIRECT na requisição de pré-verificação CORS

As solicitações feitas a um endpoint utilizando HTTP que são redirecionadas para HTTPS por UseHttpsRedirection falham com ERR_INVALID_REDIRECT na requisição preflight do 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 de produção ASP.NET Core usem:

• HTTPS Redirection Middleware (UseHttpsRedirection) para redirecionar solicitações HTTP para HTTPS.
• Middleware HSTS (UseHsts) para enviar cabeçalhos HSTS (HTTP Strict Transport Security Protocol) aos clientes.

Observação

Os aplicativos implantados em uma configuração de proxy reverso permitem que o proxy manipule a segurança da conexão (HTTPS). Se o proxy também lida com o redirecionamento HTTPS, não há necessidade de usar o middleware de redirecionamento HTTPS. Se o servidor proxy também escreve cabeçalhos HSTS (por exemplo, suporte nativo a HSTS no IIS 10.0 (1709) ou posterior), o middleware HSTS não é necessário para a aplicação. Para obter mais informações, consulte Cancele HTTPS/HSTS na criação do projeto.

UseHttpsRedirecionamento

O seguinte código chama UseHttpsRedirection no ficheiro 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 HttpsRedirectionOptions.RedirectStatusCode padrão (Status307TemporaryRedirect).
• Usa a HttpsRedirectionOptions.HttpsPort padrão (null), a menos que seja substituída pela variável de ambiente ASPNETCORE_HTTPS_PORT ou IServerAddressesFeature.

Recomendamos o uso de redirecionamentos temporários em vez de permanentes. O cache de link pode causar um comportamento instável em ambientes de desenvolvimento. Caso prefira enviar um código de estado de redirecionamento permanente quando a aplicação estiver em um ambiente não relacionado ao desenvolvimento, consulte a seção Configurar redirecionamentos permanentes em produção. Recomendamos o uso de HSTS para indicar aos clientes que apenas pedidos de recursos seguros devem ser enviados para a aplicação (apenas em produção).

Configuração da porta

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

• O redirecionamento para HTTPS não ocorre.
• 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 configuração de host https_port:

  • Na configuração do host.

  • Definindo a variável de ambiente ASPNETCORE_HTTPS_PORT.

  • Ao adicionar 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 implementações de proxy reverso.

• Os modelos da Web ASP.NET Core definem uma URL HTTPS em Properties/launchsettings.json para Kestrel e IIS Express. launchsettings.json é usado apenas na máquina local.

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

Observação

Quando um aplicativo é executado em uma configuração de proxy reverso, IServerAddressesFeature não está disponível. Defina a porta usando uma das outras abordagens descritas nesta seção.

Implantações de borda

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

• A porta segura para onde o cliente é redirecionado (normalmente, 443 em produção e 5001 em desenvolvimento).
• O porto inseguro (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 numa configuração de proxy reverso, use Middleware de Encaminhamento de Cabeçalhos antes de chamar o Middleware de Redirecionamento HTTPS. O Middleware de Cabeçalhos Encaminhados atualiza o Request.Scheme, usando o cabeçalho X-Forwarded-Proto. O middleware permite redirecionar URIs e outras políticas de segurança para funcionar corretamente. Quando o middleware de cabeçalhos encaminhados não é utilizado, a aplicação de back-end pode não receber o esquema correto e acabar num loop de redirecionamento. Uma mensagem de erro comum do usuário final é que ocorreram muitos redirecionamentos.

Ao implantar no Serviço de Aplicativo do Azure, siga as orientações em Tutorial: Vincular um certificado SSL personalizado existente ao Azure Web Apps.

Opções

As seguintes linhas de código realçadas invocam o 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();

Chamar AddHttpsRedirection só é necessário 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 assume como padrão o envio de um Status307TemporaryRedirect com todos os redirecionamentos. Se preferir enviar um código de status de redirecionamento permanente quando a aplicação estiver num ambiente não de desenvolvimento, envolva a configuração das opções do middleware numa verificação condicional para um ambiente não de desenvolvimento.

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 para o middleware de redirecionamento HTTPS

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

Ao redirecionar para HTTPS sem a necessidade de regras de redirecionamento adicionais, recomendamos o uso do middleware de redirecionamento HTTPS (UseHttpsRedirection) descrito neste artigo.

Protocolo HSTS (Strict Transport Security Protocol) HTTP

De acordo com OWASP, HTTP Strict Transport Security (HSTS) é um aprimoramento de segurança opcional especificado por um aplicativo Web por meio do uso de um cabeçalho de resposta. Quando um navegador que suporta HSTS recebe este 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 toda a comunicação através de HTTPS.
• O navegador impede que o usuário use certificados não confiáveis ou inválidos. O navegador desativa os prompts que permitem que um usuário confie temporariamente em tal certificado.

Porque HSTS é aplicado pelo cliente, existem algumas limitações:

• O cliente deve suportar 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 redirecionar ou rejeitar a solicitação HTTP.

ASP.NET Core implementa HSTS com o método de extensão UseHsts. O código a seguir chama UseHsts quando a aplicação 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 de HSTS são altamente armazenáveis em cache pelos 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 para um pequeno valor 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 confiar na sustentabilidade da configuração HTTPS, aumente o valor do HSTS max-age; um valor normalmente utilizado é de um ano.

O seguinte código destacado:

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 preload do cabeçalho Strict-Transport-Security. O pré-carregamento não faz parte da especificação RFC HSTS , mas é suportado pelos navegadores da Web para pré-carregar sites HSTS em nova instalação. Para obter mais informações, consulte https://hstspreload.org/.
• Permite includeSubDomain, que aplica a política HSTS aos subdomínios do host.
• Define explicitamente o parâmetro max-age do cabeçalho Strict-Transport-Security para 60 dias. Se não estiver definido, o padrão é de 30 dias. Para obter mais informações, consulte a diretiva max-age.
• Adiciona example.com à lista de anfitriões a excluir.

UseHsts exclui os seguintes hosts de loopback:

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

Exclusão de HTTPS/HSTS na criação de projetos

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

Para desativar HTTPS/HSTS:

Estúdio Visual

Desmarque a caixa de seleção Configurar para HTTPS.

CLI do .NET

Use a opção --no-https. Por exemplo

dotnet new webapp --no-https

Confie no certificado de desenvolvimento HTTPS do ASP.NET Core

O SDK do .NET Core inclui um certificado de desenvolvimento HTTPS. O certificado é instalado como parte da experiência de utilização inicial. Por exemplo, dotnet --info 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 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, execute a etapa única para executar a ferramenta dotnet dev-certs:

dotnet dev-certs https --trust

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

dotnet dev-certs https --help

Advertência

Não crie um certificado de desenvolvimento em um ambiente que será redistribuído, como uma imagem de contêiner ou máquina virtual. Fazer isso pode levar à falsificação e elevação de privilégios. Para ajudar a evitar isso, defina a variável de ambiente DOTNET_GENERATE_ASPNET_CERTIFICATE como false antes de chamar a CLI do .NET pela primeira vez. Isso ignorará a geração automática do certificado de desenvolvimento ASP.NET Core durante a primeira experiência de execução da CLI.

Como configurar um certificado de desenvolvedor para o Docker

Veja o sobre este problema do GitHub.

Considerações específicas do Linux

As distribuições Linux diferem substancialmente na forma como marcam os certificados como confiáveis. Embora se espere que dotnet dev-certs seja amplamente aplicável, ele só é oficialmente suportado no Ubuntu e Fedora e visa especificamente garantir a confiança no Firefox e navegadores baseados no Chromium (Edge, Chrome e Chromium).

Dependências

Para estabelecer a confiança do OpenSSL, a ferramenta openssl deve estar no PATH.

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

Confiança OpenSSL

Quando o certificado de desenvolvimento ASP.NET Core é confiável, ele é exportado para uma pasta no diretório base do usuário atual. Para que OpenSSL (e os clientes que a consomem) peguem essa pasta, você precisa definir a variável de ambiente SSL_CERT_DIR. Você pode fazer isso 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 estará na saída quando --verbose for passado) ou adicionando-o ao seu arquivo de configuração (específico da distro e do shell) (por exemplo, .profile).

Isso é necessário para fazer com que ferramentas como curl confiem no certificado de desenvolvimento. Ou, alternativamente, você pode passar -CAfile ou -CApath para cada invocação individual curl.

Observe que isso requer 1.1.1h ou posterior ou 3.0.0 ou posterior, dependendo da versão principal que você está usando.

Se a confiança no OpenSSL entrar num mau estado (por exemplo, se dotnet dev-certs https --clean não conseguir removê-la), frequentemente é possível resolver o problema usando a ferramenta c_rehash.

Substituições

Se você estiver usando outro navegador com seu próprio armazenamento NSS (Serviços de Segurança de Rede), poderá usar a variável de ambiente DOTNET_DEV_CERTS_NSSDB_PATHS para especificar uma lista delimitada por dois pontos de diretórios NSS (por exemplo, o diretório que contém cert9.db) aos quais adicionar o certificado de desenvolvimento.

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

Advertência

Se você definir qualquer uma dessas variáveis, é importante que elas sejam definidas com os mesmos valores sempre que a confiança for atualizada. Se os certificados mudarem de local, a ferramenta não terá conhecimento dos certificados nos locais antigos (por exemplo, para os remover).

Usando sudo

Como em outras plataformas, os certificados de desenvolvimento são armazenados e confiáveis separadamente para cada usuário. Como resultado, se se executar dotnet dev-certs como um utilizador diferente (por exemplo, usando sudo), é que utilizador (por exemplo, root) que confiará no certificado de desenvolvimento.

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

linux-dev-certs é uma ferramenta global .NET de código aberto e suportada pela comunidade que fornece uma maneira conveniente de criar e confiar em um certificado de desenvolvedor no Linux. A ferramenta não é mantida ou suportada pela 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.

Servidor SUSE Linux Enterprise

Veja este problema do GitHub

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

Esta seção fornece ajuda quando o certificado de desenvolvimento ASP.NET Core HTTPS 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 ASP.NET Core é usado pelo Kestrel.

Para reparar o certificado do IIS Express, consulte este problema no 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 pelos navegadores.

O comando "dotnet dev-certs https --clean" falhou

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

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

Windows - certificado não confiável

• Verifique os certificados no repositório de certificados. Deve existir um certificado localhost com um nome amigável ASP.NET Core HTTPS development certificate tanto em Current User > Personal > Certificates como em 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 KeyChain Access.
• Selecione o Porta-chaves do sistema.
• Verifique a presença de um certificado localhost.
• Verifique se ele contém um símbolo de + no ícone para indicar que é confiável para todos os usuários.
• Remova o certificado das 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 o IIS Express (dotnet/AspNetCore #16892) para solucionar problemas de certificado com o Visual Studio.

Certificado 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 de desenvolvedor HTTPS Kestrel padrão do usuário atual no seguinte local:

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

O ficheiro de certificado Kestrel do desenvolvedor HTTPS é o certificado de 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, pode ser um dos seguintes:

• Um certificado antigo.
• Exportou-se um certificado de desenvolvedor para o usuário raiz. Para este caso, exporte o certificado.

O certificado de 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. Para obter mais informações, consulte esta questão 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. Para obter mais informações, consulte esta questão do GitHub.

Informações adicionais

• Configurar o ASP.NET Core para trabalhar com servidores proxy e balanceadores de carga
• Hospedar ASP.NET Core no Linux com Nginx: Configuração HTTPS
• Como configurar SSL no IIS
• Configurar pontos de extremidade para o servidor web ASP.NET Core Kestrel
• Suporte a navegadores OWASP HSTS