Hospedar imagens ASP.NET Core com o Docker em HTTPS

De Rick Anderson

O ASP.NET Core usa HTTPS por padrão. O HTTPS depende de certificados para confiança, identity e criptografia.

Esse documento explica como executar imagens de contêiner pré-criadas com HTTPS usando a CLI (interface de linha de comando) do .NET. Para obter instruções sobre como executar o Docker em desenvolvimento com o Visual Studio, consulte Como desenvolver aplicativos ASP.NET Core com o Docker por HTTPS.

Esse exemplo instala o Docker 17.06 ou posterior do cliente do Docker.

Pré-requisitos

O SDK do .NET atual.

Certificados

Um certificado de uma autoridade de certificação é necessário para uma hospedagem de produção para um domínio. Let's Encrypt é uma autoridade de certificação que oferece certificados gratuitos.

Este documento usa certificados de desenvolvimento autoassinados para hospedar imagens pré-criadas por meio de localhost. As instruções são semelhantes ao uso de certificados de produção. O certificado gerado por dotnet dev-certs é para uso somente com localhost e não deve ser usado em um ambiente como o Kubernetes. Para dar suporte a HTTPS em um cluster do Kubernetes, use as ferramentas fornecidas por Gerenciar certificados TLS em um cluster para configurar o TLS em pods.

Use dotnet dev-certs para criar certificados autoassinados para desenvolvimento e teste.

Para certificados de produção:

• A ferramenta dotnet dev-certs não é necessária.
• Os certificados não precisam ser armazenados no local usado nas instruções. Qualquer local deve funcionar, embora o armazenamento de certificados no diretório do site não seja recomendado.

As instruções contidas na seção a seguir montam certificados de montagem de volume em contêineres usando a opção de linha de comando -v do Docker. Você pode adicionar certificados em imagens de contêiner com um comando COPY em um Dockerfile, mas isso não é recomendado. A cópia de certificados em uma imagem não é recomendada pelos seguintes motivos:

• É difícil usar a mesma imagem para teste com certificados de desenvolvedor.
• É difícil usar a mesma imagem para Hospedagem com certificados de produção.
• Há um risco significativo de divulgação de certificado.

Como executando imagens de contêiner predefinidas com HTTPS

Use as instruções a seguir para a configuração do sistema operacional.

Windows usando contêineres do Linux

Gere um certificado e configure o computador local:

dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

Nos comandos anteriores, substitua <CREDENTIAL_PLACEHOLDER> por uma senha.

Execute a imagem de contêiner com o ASP.NET Core configurado para HTTPS em um shell de comando:

docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx -v %USERPROFILE%\.aspnet\https:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp

No código anterior, substitua <CREDENTIAL_PLACEHOLDER> pela senha. A senha deve corresponder à senha usada para o certificado.

Ao usar o PowerShell, substitua %USERPROFILE% por $env:USERPROFILE.

Observação: o certificado nesse caso deve ser um arquivo .pfx. Não há suporte para a utilização de um arquivo .crt ou .key com ou sem a senha com o contêiner de exemplo. Por exemplo, ao especificar um arquivo .crt, o contêiner pode retornar mensagens de erro como "O SSL do modo de servidor deve usar um certificado com a chave privada associada". Ao usar WSL, valide o caminho de montagem para garantir que o certificado seja carregado corretamente.

macOS ou Linux

Para gerar um certificado e configurar um computador local:

dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

No Linux, dotnet dev-certs https --trust requer o .NET 9 ou versões posteriores. Para o Linux no SDK do .NET 8.0.401 e versões anteriores, veja a documentação da distribuição do Linux para confiar em um certificado.

Nos comandos anteriores, substitua <CREDENTIAL_PLACEHOLDER> por uma senha.

Execute a imagem do contêiner com ASP.NET Core configurado para HTTPS:

docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx -v ${HOME}/.aspnet/https:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp

No código anterior, substitua <CREDENTIAL_PLACEHOLDER> pela senha. A senha deve corresponder à senha usada para o certificado.

Windows que usa contêineres do Windows

Para gerar um certificado e configurar um computador local:

dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

Nos comandos anteriores, substitua <CREDENTIAL_PLACEHOLDER> por uma senha. Ao usar o PowerShell, substitua %USERPROFILE% por $env:USERPROFILE.

Execute a imagem do contêiner com ASP.NET Core configurado para HTTPS:

docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=c:\https\aspnetapp.pfx -v %USERPROFILE%\.aspnet\https:C:\https\ --user ContainerAdministrator mcr.microsoft.com/dotnet/samples:aspnetapp

OBSERVAÇÃO:<CREDENTIAL_PLACEHOLDER> é um espaço reservado para a senha padrão dos certificados Kestrel.

A senha deve corresponder à senha usada para o certificado. Ao usar o PowerShell, substitua %USERPROFILE% por $env:USERPROFILE.

Como desenvolver aplicativos ASP.NET Core com o Docker em HTTPS

Consulte Como desenvolvendo aplicativos do ASP.NET Core com o Docker por HTTPS para obter informações e exemplos sobre como desenvolver aplicativos do ASP.NET Core com HTTPS em contêineres do Docker.

Confira também

• Como desenvolver aplicativos ASP.NET Core com o Docker em HTTPS
• dotnet dev-certs

O ASP.NET Core usa HTTPS por padrão. O HTTPS depende de certificados para confiança, identity e criptografia.

Esse documento explica como executar imagens de contêiner pré-criadas com HTTPS usando a CLI (interface de linha de comando) do .NET. Para obter instruções sobre como executar o Docker em desenvolvimento com o Visual Studio, consulte Como desenvolver aplicativos ASP.NET Core com o Docker por HTTPS.

Esse exemplo instala o Docker 17.06 ou posterior do cliente do Docker.

Pré-requisitos

O SDK do .NET atual.

Certificados

Um certificado de uma autoridade de certificação é necessário para uma hospedagem de produção para um domínio. Let's Encrypt é uma autoridade de certificação que oferece certificados gratuitos.

Este documento usa certificados de desenvolvimento autoassinados para hospedar imagens pré-criadas por meio de localhost. As instruções são semelhantes ao uso de certificados de produção. O certificado gerado por dotnet dev-certs é para uso somente com localhost e não deve ser usado em um ambiente como o Kubernetes. Para dar suporte a HTTPS em um cluster do Kubernetes, use as ferramentas fornecidas por Gerenciar certificados TLS em um cluster para configurar o TLS em pods.

Use dotnet dev-certs para criar certificados autoassinados para desenvolvimento e teste.

Para certificados de produção:

• A ferramenta dotnet dev-certs não é necessária.
• Os certificados não precisam ser armazenados no local usado nas instruções. Qualquer local deve funcionar, embora o armazenamento de certificados no diretório do site não seja recomendado.

As instruções contidas na seção a seguir montam certificados de montagem de volume em contêineres usando a opção de linha de comando -v do Docker. Você pode adicionar certificados em imagens de contêiner com um comando COPY em um Dockerfile, mas isso não é recomendado. A cópia de certificados em uma imagem não é recomendada pelos seguintes motivos:

• É difícil usar a mesma imagem para teste com certificados de desenvolvedor.
• É difícil usar a mesma imagem para Hospedagem com certificados de produção.
• Há um risco significativo de divulgação de certificado.

Como executando imagens de contêiner predefinidas com HTTPS

Use as instruções a seguir para a configuração do sistema operacional.

Windows usando contêineres do Linux

Gere um certificado e configure o computador local:

dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

Nos comandos anteriores, substitua <CREDENTIAL_PLACEHOLDER> por uma senha.

Execute a imagem de contêiner com o ASP.NET Core configurado para HTTPS em um shell de comando:

docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx -v %USERPROFILE%\.aspnet\https:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp

No código anterior, substitua <CREDENTIAL_PLACEHOLDER> pela senha. A senha deve corresponder à senha usada para o certificado.

Ao usar o PowerShell, substitua %USERPROFILE% por $env:USERPROFILE.

Observação: o certificado nesse caso deve ser um arquivo .pfx. Não há suporte para a utilização de um arquivo .crt ou .key com ou sem a senha com o contêiner de exemplo. Por exemplo, ao especificar um arquivo .crt, o contêiner pode retornar mensagens de erro como "O SSL do modo de servidor deve usar um certificado com a chave privada associada". Ao usar WSL, valide o caminho de montagem para garantir que o certificado seja carregado corretamente.

macOS ou Linux

Para gerar um certificado e configurar um computador local:

dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

O dotnet dev-certs https --trust só é compatível com macOS e Windows. Você precisa confiar em certificados no Linux da maneira que é compatível com sua distribuição. É provável que você precise confiar no certificado no navegador.

Nos comandos anteriores, substitua <CREDENTIAL_PLACEHOLDER> por uma senha.

Execute a imagem do contêiner com ASP.NET Core configurado para HTTPS:

docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx -v ${HOME}/.aspnet/https:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp

No código anterior, substitua <CREDENTIAL_PLACEHOLDER> pela senha. A senha deve corresponder à senha usada para o certificado.

Windows que usa contêineres do Windows

Para gerar um certificado e configurar um computador local:

dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
dotnet dev-certs https --trust

Nos comandos anteriores, substitua <CREDENTIAL_PLACEHOLDER> por uma senha. Ao usar o PowerShell, substitua %USERPROFILE% por $env:USERPROFILE.

Execute a imagem do contêiner com ASP.NET Core configurado para HTTPS:

docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
docker run --rm -it -p 8000:80 -p 8001:443 -e ASPNETCORE_URLS="https://+;http://+" -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=c:\https\aspnetapp.pfx -v %USERPROFILE%\.aspnet\https:C:\https\ --user ContainerAdministrator mcr.microsoft.com/dotnet/samples:aspnetapp

OBSERVAÇÃO:<CREDENTIAL_PLACEHOLDER> é um espaço reservado para a senha padrão dos certificados Kestrel.

A senha deve corresponder à senha usada para o certificado. Ao usar o PowerShell, substitua %USERPROFILE% por $env:USERPROFILE.

Como desenvolver aplicativos ASP.NET Core com o Docker em HTTPS

Consulte Como desenvolvendo aplicativos do ASP.NET Core com o Docker por HTTPS para obter informações e exemplos sobre como desenvolver aplicativos do ASP.NET Core com HTTPS em contêineres do Docker.

Confira também

• Como desenvolver aplicativos ASP.NET Core com o Docker em HTTPS
• dotnet dev-certs