AspNetCore.Docs/aspnetcore/security/docker-https.md

title	author	description	monikerRange	ms.author	ms.custom	ms.date	no-loc	uid
Hosting ASP.NET Core Images with Docker over HTTPS	rick-anderson	Learn how to host ASP.NET Core Images with Docker over HTTPS	>= aspnetcore-2.1	riande	mvc	07/05/2019	appsettings.json ASP.NET Core Identity cookie Cookie Blazor Blazor Server Blazor WebAssembly Identity Let's Encrypt Razor SignalR	security/docker-https

Hosting ASP.NET Core images with Docker over HTTPS

By Rick Anderson

ASP.NET Core uses HTTPS by default. HTTPS relies on certificates for trust, identity, and encryption.

This document explains how to run pre-built container images with HTTPS.

See Developing ASP.NET Core Applications with Docker over HTTPS for development scenarios.

This sample requires Docker 17.06 or later of the Docker client.

Prerequisites

The .NET Core 2.2 SDK or later is required for some of the instructions in this document.

Certificates

A certificate from a certificate authority is required for production hosting for a domain. Let's Encrypt is a certificate authority that offers free certificates.

This document uses self-signed development certificates for hosting pre-built images over localhost. The instructions are similar to using production certificates.

For production certs:

• The dotnet dev-certs tool is not required.
• Certificates do not need to be stored in the location used in the instructions. Any location should work, although storing certs within your site directory is not recommended.

The instructions contained in the following section volume mount certificates into containers using Docker's -v command-line option. You could add certificates into container images with a COPY command in a Dockerfile, but it's not recommended. Copying certificates into an image isn't recommended for the following reasons:

• It makes difficult to use the same image for testing with developer certificates.
• It makes difficult to use the same image for Hosting with production certificates.
• There is significant risk of certificate disclosure.

Running pre-built container images with HTTPS

Use the following instructions for your operating system configuration.

Windows using Linux containers

Generate certificate and configure local machine:

dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p { password here }
dotnet dev-certs https --trust

In the preceding commands, replace { password here } with a password.

Run the container image with ASP.NET Core configured for HTTPS in a command shell:

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

When using PowerShell, replace %USERPROFILE% with $env:USERPROFILE.

The password must match the password used for the certificate.

macOS or Linux

Generate certificate and configure local machine:

dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p { password here }
dotnet dev-certs https --trust

dotnet dev-certs https --trust is only supported on macOS and Windows. You need to trust certs on Linux in the way that is supported by your distribution. It is likely that you need to trust the certificate in your browser.

In the preceding commands, replace { password here } with a password.

Run the container image with ASP.NET Core configured for HTTPS:

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

The password must match the password used for the certificate.

Windows using Windows containers

Generate certificate and configure local machine:

dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p { password here }
dotnet dev-certs https --trust

In the preceding commands, replace { password here } with a password. When using PowerShell, replace %USERPROFILE% with $env:USERPROFILE.

Run the container image with ASP.NET Core configured for HTTPS:

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

The password must match the password used for the certificate. When using PowerShell, replace %USERPROFILE% with $env:USERPROFILE.