129 lines
7.5 KiB
Markdown
129 lines
7.5 KiB
Markdown
---
|
|
title: Hosting ASP.NET Core Images with Docker over HTTPS
|
|
author: rick-anderson
|
|
description: Learn how to host ASP.NET Core Images with Docker over HTTPS
|
|
ms.author: wpickett
|
|
ms.custom: mvc
|
|
ms.date: 09/07/2024
|
|
uid: security/docker-https
|
|
---
|
|
# Hosting ASP.NET Core images with Docker over HTTPS
|
|
|
|
:::moniker range=">= aspnetcore-8.0"
|
|
|
|
By [Rick Anderson](https://twitter.com/RickAndMSFT)
|
|
|
|
ASP.NET Core uses [HTTPS by default](~/security/enforcing-ssl.md). [HTTPS](https://en.wikipedia.org/wiki/HTTPS) relies on [certificates](https://en.wikipedia.org/wiki/Public_key_certificate) for trust, identity, and encryption.
|
|
|
|
This document explains how to run pre-built container images with HTTPS using the [.NET command-line interface (CLI)](/dotnet/core/tools/). For instructions on how to run Docker in development with Visual Studio, see [Developing ASP.NET Core Applications with Docker over HTTPS](https://github.com/dotnet/dotnet-docker/blob/main/samples/run-aspnetcore-https-development.md).
|
|
|
|
This sample requires [Docker 17.06](https://docs.docker.com/release-notes/docker-ce) or later of the [Docker client](https://www.docker.com/products/docker).
|
|
|
|
## Prerequisites
|
|
|
|
The current [.NET SDK](https://dotnet.microsoft.com/download).
|
|
|
|
## Certificates
|
|
|
|
A certificate from a [certificate authority](https://wikipedia.org/wiki/Certificate_authority) is required for [production hosting](https://blogs.msdn.microsoft.com/webdev/2017/11/29/configuring-https-in-asp-net-core-across-different-platforms/) for a domain. [:::no-loc text="Let's Encrypt":::](https://letsencrypt.org/) is a certificate authority that offers free certificates.
|
|
|
|
This document uses [self-signed development certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) for hosting pre-built images over `localhost`. The instructions are similar to using production certificates. The certificate generated by `dotnet dev-certs` is for use with `localhost` only and should ***not*** be used in an environment like Kubernetes. To support HTTPS within a Kubernetes cluster, use the tools provided by [Manage TLS Certificates in a Cluster](https://kubernetes.io/docs/tasks/tls/managing-tls-in-a-cluster/) to setup TLS within pods.
|
|
|
|
Use [`dotnet dev-certs`](/dotnet/core/tools/dotnet-dev-certs) to create self-signed certificates for development and testing.
|
|
|
|
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's difficult to use the same image for testing with developer certificates.
|
|
* It's 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 a certificate and configure the local machine:
|
|
|
|
```dotnetcli
|
|
dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
|
|
dotnet dev-certs https --trust
|
|
```
|
|
|
|
In the preceding commands, replace `<CREDENTIAL_PLACEHOLDER>` with a password.
|
|
|
|
Run the container image with ASP.NET Core configured for HTTPS in a command shell:
|
|
|
|
```console
|
|
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
|
|
```
|
|
|
|
In the preceding code, replace `<CREDENTIAL_PLACEHOLDER>` with the password. The password must match the password used for the certificate.
|
|
|
|
When using [PowerShell](/powershell/scripting/overview), replace `%USERPROFILE%` with `$env:USERPROFILE`.
|
|
|
|
Note: The certificate in this case must be a `.pfx` file. Utilizing a `.crt` or `.key` file with or without the password isn't supported with the sample container. For example, when specifying a `.crt` file, the container may return error messages such as 'The server mode SSL must use a certificate with the associated private key.'. When using [WSL](/windows/wsl/about), validate the mount path to ensure that the certificate loads correctly.
|
|
|
|
### macOS or Linux
|
|
|
|
Generate certificate and configure local machine:
|
|
|
|
```dotnetcli
|
|
dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
|
|
dotnet dev-certs https --trust
|
|
```
|
|
|
|
On Linux, `dotnet dev-certs https --trust` requires .NET 9 SDK or later. For Linux on .NET 8.0.401 SDK and earlier, see your Linux distribution's documentation for trusting a certificate.
|
|
|
|
In the preceding commands, replace `<CREDENTIAL_PLACEHOLDER>` with a password.
|
|
|
|
Run the container image with ASP.NET Core configured for HTTPS:
|
|
|
|
```console
|
|
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
|
|
```
|
|
|
|
In the preceding code, replace `<CREDENTIAL_PLACEHOLDER>` with the password. The password must match the password used for the certificate.
|
|
|
|
### Windows using Windows containers
|
|
|
|
Generate certificate and configure local machine:
|
|
|
|
```dotnetcli
|
|
dotnet dev-certs https -ep %USERPROFILE%\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
|
|
dotnet dev-certs https --trust
|
|
```
|
|
|
|
In the preceding commands, replace `<CREDENTIAL_PLACEHOLDER>` with a password. When using [PowerShell](/powershell/scripting/overview), replace `%USERPROFILE%` with `$env:USERPROFILE`.
|
|
|
|
Run the container image with ASP.NET Core configured for HTTPS:
|
|
|
|
```console
|
|
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
|
|
```
|
|
|
|
***NOTE:*** `<CREDENTIAL_PLACEHOLDER>` is a placeholder for the Kestrel certificates default password.
|
|
|
|
The password must match the password used for the certificate. When using [PowerShell](/powershell/scripting/overview), replace `%USERPROFILE%` with `$env:USERPROFILE`.
|
|
|
|
## Developing ASP.NET Core Applications with Docker over HTTPS
|
|
|
|
See [Developing ASP.NET Core Applications with Docker over HTTPS](https://github.com/dotnet/dotnet-docker/blob/master/samples/run-aspnetcore-https-development.md) for information and samples on how to develop ASP.NET Core applications with HTTPS in Docker containers.
|
|
|
|
## See also
|
|
|
|
* [Developing ASP.NET Core Applications with Docker over HTTPS](https://github.com/dotnet/dotnet-docker/blob/main/samples/run-aspnetcore-https-development.md)
|
|
* [`dotnet dev-certs`](/dotnet/core/tools/dotnet-dev-certs)
|
|
|
|
:::moniker-end
|
|
|
|
[!INCLUDE[](~/security/includes/docker-https6.md)]
|