Re-write ASP.NET Core HTTPS documentation (#6117)

lbussell · Rick-Anderson · web-flow · commit f0d4a41d0830 · 2025-01-07T08:18:43.000-08:00
Co-authored-by: Rick Anderson &lt;3605364+Rick-Anderson@users.noreply.github.com&gt;
diff --git a/samples/host-aspnetcore-https.md b/samples/host-aspnetcore-https.md
@@ -2,97 +2,11 @@
 
 ASP.NET Core uses [HTTPS by default](https://docs.microsoft.com/aspnet/core/security/enforcing-ssl). [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.
+See [Hosting ASP.NET Core images with Docker over HTTPS](https://learn.microsoft.com/en-us/aspnet/core/security/docker-https) for [HTTPS](https://en.wikipedia.org/wiki/HTTPS) scenarios
 
-See [Developing ASP.NET Core Applications with Docker over HTTPS](run-aspnetcore-https-development.md) for development scenarios.
+## Get certificates into a container
 
-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).
+The instructions show how to [bind-mount](https://docs.docker.com/engine/storage/bind-mounts/) certificates into containers. We recommend certificates ***NOT*** be added into the image with a `COPY` command in a Dockerfile for the following reasons:
 
-## Certificates
-
-You need a certificate from a [certificate authority](https://en.wikipedia.org/wiki/Certificate_authority) for [production hosting](https://blogs.msdn.microsoft.com/webdev/2017/11/29/configuring-https-in-asp-net-core-across-different-platforms/) for your domain. You may already have one. [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.
-
-For production certs, you do not need to use the `dotnet dev-certs` tool or store the certificates in the location used in the instructions. Any location should work, although storing certs within your site directory is an anti-pattern.
-
-The instructions volume mount certificates into containers. You can add certificates into container images with a `COPY` command in a Dockerfile. Copying certificates into an image is an anti-pattern. It makes it harder to use the same image for testing with dev certificates and hosting with production certificates. There is also a  significant risk of certificate disclosure if certificates are made part of container images.
-
-## Running pre-built Container Images with HTTPS
-
-Use the following instructions for your operating system configuration.
-
-### Linux containers on Windows host
-
-Generate cert and configure local machine:
-
-> [!NOTE]
-> If you are using CMD instead of PowerShell, substitute `$env:USERPROFILE` with `%USERPROFILE%`.
-
-```console
-dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
-dotnet dev-certs https --trust
-```
-
-> [!NOTE]
-> `<CREDENTIAL_PLACEHOLDER>` is used as a stand-in for a password of your own choosing.
-
-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 8001:8001 -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx -v $env:USERPROFILE\.aspnet\https:/https/ mcr.microsoft.com/dotnet/samples:aspnetapp
-```
-
-> [!NOTE]
-> The password must match the password used for the certificate.
-
-### Linux containers on macOS or Linux host
-
-Create a certificate directory with appropriate permissions:
-
-```console
-mkdir -p -m 700 ${HOME}/.aspnet/https
-```
-
-Generate cert and configure local machine:
-
-```console
-dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
-dotnet dev-certs https --trust
-```
-
-> [!NOTE]
-> `<CREDENTIAL_PLACEHOLDER>` is used as a stand-in for a password of your own choosing.
-
-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 8001:8001 -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
-```
-
-> [!NOTE]
-> The password must match the password used for the certificate.
-
-### Windows containers on Windows host
-
-Generate cert and configure local machine:
-
-```console
-dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
-dotnet dev-certs https --trust
-```
-
-> [!NOTE]
-> `<CREDENTIAL_PLACEHOLDER>` is used as a stand-in for a password of your own choosing.
-
-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 8001:8001 -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_Kestrel__Certificates__Default__Password="<CREDENTIAL_PLACEHOLDER>" -e ASPNETCORE_Kestrel__Certificates__Default__Path=\https\aspnetapp.pfx -v $env:USERPROFILE\.aspnet\https:C:\https\ --user ContainerAdministrator mcr.microsoft.com/dotnet/samples:aspnetapp
-```
-
-> [!NOTE]
-> The password must match the password used for the certificate. Running as ContainerAdministrator is not recommended in production scenarios. The `--user ContainerAdministrator` flag has been added in this example since there is a potential and intermittent race condition that throws a `WindowsCryptographicException` at the container/app startup when using self-signed certificates. This is a known bug and it has been [reported here](https://github.com/dotnet/runtime/issues/70386).
+* It makes it harder to use the same image for testing with dev certificates and hosting with production certificates.
+* It increases the risk of certificate disclosure if certificates are made part of your container image.
diff --git a/samples/run-aspnetcore-https-development.md b/samples/run-aspnetcore-https-development.md
@@ -4,236 +4,98 @@ ASP.NET Core uses [HTTPS by default](https://docs.microsoft.com/aspnet/core/secu
 
 This document demonstrates how to develop ASP.NET Core applications with HTTPS in Docker containers. It's recommended to try the [ASP.NET Core Docker Sample](README.md) first, which is simpler because the container only exposes HTTP. This more basic tutorial will help you validate that you have the sample working correctly, before adding the complication of certificates.
 
-See [Hosting ASP.NET Core Images with Docker over HTTPS](host-aspnetcore-https.md) for production scenarios.
+See [Hosting ASP.NET Core images with Docker over HTTPS](https://learn.microsoft.com/en-us/aspnet/core/security/docker-https) for production scenarios.
 
-The Windows examples below are written for PowerShell. CMD users will need to change the format of the environment variables in the instructions from `$env:USERPROFILE` to `%USERPROFILE%`.
+Windows instructions are written for PowerShell. If you are using CMD, change the format of environment variables from `${env:USERPROFILE}` to `%USERPROFILE%`.
 
-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).
+This example requires [Docker Desktop](https://www.docker.com/products/docker-desktop/). We recommend the latest version.
 
-## Getting the sample
+## Getting the sample image
 
-The easiest way to get the sample is by cloning the samples repository with git, using the following instructions:
+Pull the sample image:
 
 ```console
-git clone https://github.com/dotnet/dotnet-docker/
-```
-
-You can also [download the repository as a zip](https://github.com/dotnet/dotnet-docker/archive/main.zip).
-
-## Certificates
-
-ASP.NET Core uses [self-signed development certificates](https://en.wikipedia.org/wiki/Self-signed_certificate) for development. Self-signed certificates are easy and free to create.
-
-The instructions volume mount certificates into containers. You can add certificates into container images with a `COPY` command in a Dockerfile. This approach isn't recommended. It makes it harder to use the same image for testing with dev certificates and hosting with production certificates. There's also a  significant risk of certificate disclosure if certificates are made part of container images.
-
-## Application Secrets
-
-These instructions assume that your project is configured for [application secrets](https://docs.microsoft.com/aspnet/core/security/app-secrets). The primary requirement is a [UserSecretsId](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj#L5) element in your project file. If you're using the ASP.NET Core sample in this repo, you don't need to do anything. It's already correctly configured. If you're using your own project file, add an `UserSecretsId` element.
-
-You can add the element manually or use Visual Studio to do it for you. The following image demonstrates the experience in Visual Studio.
-
-![Manage user secrets in Visual Studio](https://user-images.githubusercontent.com/7681382/39641521-85d4a7b4-4f9c-11e8-9466-d1ff56db33cb.png)
-
-The format of the `UserSecretsId` content doesn't matter. The sample in this repo used [Random String Generator](https://www.random.org/strings/?num=6&len=20&digits=on&unique=on&format=html&rnd=new) to produce a unique string.
-
-> [!NOTE]
-> `User Secrets` and `Application Secrets` terms are used interchangebly.
-
-## Building and Running the Sample with HTTPS
-
-Use the following instructions, for your operating system configuration. The commands assume that you are in the root of the repository.
-
-> [!NOTE]
-> The sample includes a banner to accept a cookie policy. When switching between HTTP and HTTPS, you may see the banner repeatedly. Delete the cookie for the site in `Developer Tools` in this case.
-
-![Developer Tools -- Delete cookie](https://user-images.githubusercontent.com/2608468/40246148-875fee5a-5a7c-11e8-9728-7da89a491014.png)
-
-Further, if you're loading SSL certificates and trimming assemblies as part of the publish, you'll also need to update the project file for the sample.  See details for how you can [support SSL certificates](https://docs.microsoft.com/en-us/dotnet/core/deploying/trim-self-contained#support-for-ssl-certificates).
-
-### Linux containers on Windows host
-
-The following example uses PowerShell.
-
-Navigate to sample:
-
-```console
-cd samples\aspnetapp
-```
-
-Generate cert and configure local machine:
-
-```console
-dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
-dotnet dev-certs https --trust
-```
-
-> [!NOTE]
->
-> - The certificate name, in this case *aspnetapp*.pfx must match the project assembly name.
-> - `<CREDENTIAL_PLACEHOLDER>` is used as a stand-in for a password of your own choosing.
-> - If console returns "A valid HTTPS certificate is already present.", a trusted certificate already exists in your store. It can be exported using MMC Console.
-
-Configure application secrets, for the certificate:
-
-```console
-dotnet user-secrets init -p aspnetapp\aspnetapp.csproj
-dotnet user-secrets -p aspnetapp\aspnetapp.csproj set "Kestrel:Certificates:Development:Password" "<CREDENTIAL_PLACEHOLDER>"
-```
-
-> [!NOTE]
-> The password must match the password used for the certificate.
-
-Build a container image:
-
-```console
-docker build --pull -t aspnetapp .
+docker pull mcr.microsoft.com/dotnet/samples:aspnetapp
 ```
 
-Run the container image with ASP.NET Core configured for HTTPS:
+Alternatively, you can build the sample image locally:
 
 ```console
-docker run --rm -it -p 8001:8001 -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_ENVIRONMENT=Development -v $env:APPDATA\microsoft\UserSecrets\:/root/.microsoft/usersecrets -v $env:USERPROFILE\.aspnet\https:/root/.aspnet/https/ aspnetapp
+docker build --pull -t mcr.microsoft.com/dotnet/samples:aspnetapp 'https://github.com/dotnet/dotnet-docker.git#:samples/aspnetapp'
 ```
 
-After the application starts, navigate to `https://localhost:8001` in your web browser.
-
-### Linux containers on macOS host
-
-```console
-cd samples/aspnetapp
-```
+## Create and trust a development certificate
 
-Create a certificate directory with appropriate permissions:
+Follow the instructions for creating a [.NET development certificate](https://learn.microsoft.com/dotnet/core/tools/dotnet-dev-certs) from [Running pre-built container images with HTTPS](https://learn.microsoft.com/aspnet/core/security/docker-https#running-pre-built-container-images-with-https).
 
-```console
-mkdir -p -m 700 ${HOME}/.aspnet/https
-```
+## Enable HTTPS using environment variables
 
-Generate cert and configure local machine:
+See [Hosting ASP.NET Core images with Docker over HTTPS](https://learn.microsoft.com/aspnet/core/security/docker-https). See the following section if you don't want to use environment variables to store your development
+certificate password.
 
-```console
-dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
-dotnet dev-certs https --trust
-```
+## Using user secrets for certificate password
 
-> [!NOTE]
->
-> - The certificate name, in this case *aspnetapp*.pfx must match the project assembly name.
-> - `<CREDENTIAL_PLACEHOLDER>` is used as a stand-in for a password of your own choosing.
+Rather than using environment variable to specify the development certificate password,  use [.NET user secrets](https://learn.microsoft.com/aspnet/core/security/app-secrets) to store the password.
 
-Configure application secrets, for the certificate:
+Initializing user-secrets for the first time on a project modifies the project file, so you will need a local copy of the `aspnetapp` sample. Clone this repo or [download the repository as a zip](https://github.com/dotnet/dotnet-docker/archive/main.zip).
 
 ```console
-dotnet user-secrets init -p aspnetapp/aspnetapp.csproj
-dotnet user-secrets -p aspnetapp/aspnetapp.csproj set "Kestrel:Certificates:Development:Password" "<CREDENTIAL_PLACEHOLDER>"
-```
-
-> [!NOTE]
-> The password must match the password used for the certificate.
-
-Build a container image:
-
-```console
-docker build --pull -t aspnetapp .
-```
-
-Run the container image with ASP.NET Core configured for HTTPS:
-
-```console
-docker run --rm -it -p 8001:8001 -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_ENVIRONMENT=Development -v ${HOME}/.microsoft/usersecrets/:/root/.microsoft/usersecrets -v ${HOME}/.aspnet/https:/root/.aspnet/https/ aspnetapp
+git clone https://github.com/dotnet/dotnet-docker/
 ```
 
-After the application starts, navigate to `https://localhost:8001` in your web browser.
-
-### Linux containers on Linux host
+Initialize user secrets for your app, and set the certificate password:
 
 ```console
 cd samples/aspnetapp
-```
-
-Create a certificate directory with appropriate permissions:
-
-```console
-mkdir -p -m 700 ${HOME}/.aspnet/https
-```
-
-Generate cert and configure local machine:
-
-```console
-dotnet dev-certs https -ep ${HOME}/.aspnet/https/aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
-```
-
-> [!NOTE]
->
-> - The certificate name, in this case *aspnetapp*.pfx must match the project assembly name.
-> - `<CREDENTIAL_PLACEHOLDER>` is used as a stand-in for a password of your own choosing.
-
-Configure application secrets, for the certificate:
-
-```console
 dotnet user-secrets init -p aspnetapp/aspnetapp.csproj
-dotnet user-secrets -p aspnetapp/aspnetapp.csproj set "Kestrel:Certificates:Development:Password" "<CREDENTIAL_PLACEHOLDER>"
+dotnet user-secrets -p aspnetapp/aspnetapp.csproj set "Kestrel:Certificates:Default:Password" $CREDENTIAL_PLACEHOLDER
 ```
 
-Build a container image:
+Since initializing user-secrets modified the project file, re-build the sample image:
 
-```console
+```pwsh
 docker build --pull -t aspnetapp .
 ```
 
-Run the container image with ASP.NET Core configured for HTTPS:
-
-```console
-docker run --rm -it -p 8001:8001 -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_ENVIRONMENT=Development -e ASPNETCORE_Kestrel__Certificates__Development__Password="<CREDENTIAL_PLACEHOLDER>" -v ${HOME}/.microsoft/usersecrets/:/root/.microsoft/usersecrets -v ${HOME}/.aspnet/https:/root/.aspnet/https/ aspnetapp
-```
-
-After the application starts, navigate to `https://localhost:8001` in your web browser.
-
-### Windows containers on Windows host
+In Linux containers, .NET looks under the `~/.microsoft/usersecrets/` directory for user secrets data. Bind-mount your host machine's user secrets directory to the container's filesystem. If you are running your container as the `root` user, replace `/home/app/` with the `root` user's home directory, `/root/`.
 
-The following example uses PowerShell.
+**Linux containers on Windows:**
 
-Navigate to sample:
-
-```console
-cd samples\aspnetapp
+```pwsh
+docker run --rm -it `
+    -p 8001:8001 `
+    -e ASPNETCORE_HTTPS_PORTS=8001 `
+    -e ASPNETCORE_ENVIRONMENT=Development `
+    -v ${env:APPDATA}/microsoft/UserSecrets/:/home/app/.microsoft/usersecrets `
+    -v ${env:USERPROFILE}/.aspnet/https/:/https/ `
+    -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx `
+    aspnetapp
 ```
 
-Generate cert and configure local machine:
+**Linux containers on macOS or Linux:**
 
-```console
-dotnet dev-certs https -ep $env:USERPROFILE\.aspnet\https\aspnetapp.pfx -p <CREDENTIAL_PLACEHOLDER>
-dotnet dev-certs https --trust
+```bash
+docker run --rm -it \
+    -p 8001:8001 \
+    -e ASPNETCORE_HTTPS_PORTS=8001 \
+    -e ASPNETCORE_ENVIRONMENT=Development \
+    -v ${HOME}/.microsoft/usersecrets/:/home/app/.microsoft/usersecrets \
+    -v ${HOME}/.aspnet/https/:/https/ \
+    -e ASPNETCORE_Kestrel__Certificates__Default__Path=/https/aspnetapp.pfx \
+    aspnetapp
 ```
 
-> [!NOTE]
->
-> - The certificate name, in this case *aspnetapp*.pfx must match the project assembly name.
-> - `<CREDENTIAL_PLACEHOLDER>` is used as a stand-in for a password of your own choosing.
-> - If console returns "A valid HTTPS certificate is already present.", a trusted certificate already exists in your store. It can be exported using MMC Console.
+**Windows containers on Windows:**
 
-Configure application secrets, for the certificate:
-
-```console
-dotnet user-secrets init -p aspnetapp/aspnetapp.csproj
-dotnet user-secrets -p aspnetapp\aspnetapp.csproj set "Kestrel:Certificates:Development:Password" "<CREDENTIAL_PLACEHOLDER>"
+```pwsh
+docker run --rm -it `
+    -p 8001:8001 `
+    -e ASPNETCORE_HTTPS_PORTS=8001 `
+    -e ASPNETCORE_ENVIRONMENT=Development `
+    -v ${env:APPDATA}\microsoft\UserSecrets\:C:\Users\ContainerUser\AppData\Roaming\microsoft\UserSecrets `
+    -v ${env:USERPROFILE}\.aspnet\https:C:\https `
+    aspnetapp
 ```
 
-> [!NOTE]
-> The password must match the password used for the certificate.
-
-Build a container image:
-
-```console
-docker build --pull -t aspnetapp .
-```
-
-Run the container image with ASP.NET Core configured for HTTPS.
-
-```console
-docker run --rm -it -p 8001:8001 -e ASPNETCORE_HTTPS_PORTS=8001 -e ASPNETCORE_ENVIRONMENT=Development -v $env:APPDATA\microsoft\UserSecrets\:C:\Users\ContainerUser\AppData\Roaming\microsoft\UserSecrets -v $env:USERPROFILE\.aspnet\https:C:\Users\ContainerUser\AppData\Roaming\ASP.NET\Https aspnetapp
-```
-
-After the application starts, navigate to `https://localhost:8001` in your web browser.
-
-> In the case of using https, be sure to check the certificate you're using is trusted on the host. You can start with navigating to `https://localhost:8001` in the browser. If you're looking to test https with a domain name (e.g. `https://contoso.com:8001`), the certificate would also need the appropiate Subject Alternative Name included, and the DNS settings on the host would need to be updated. In the case of using the generated dev certificate, the trusted certificate will be issued from localhost and will not have the SAN added.
+After the application starts, navigate to `https://localhost:8001` in your web
+browser.
