From 5a82857ac0341c8ca2502e2999282b8be85a0b78 Mon Sep 17 00:00:00 2001 From: David Negstad Date: Wed, 11 Feb 2026 11:39:38 -0800 Subject: [PATCH 1/2] Add instructions on trusting the development certificate --- .../app-host/certificate-configuration.mdx | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/src/frontend/src/content/docs/app-host/certificate-configuration.mdx b/src/frontend/src/content/docs/app-host/certificate-configuration.mdx index 1d880360..5ab609fc 100644 --- a/src/frontend/src/content/docs/app-host/certificate-configuration.mdx +++ b/src/frontend/src/content/docs/app-host/certificate-configuration.mdx @@ -29,6 +29,63 @@ Aspire simplifies HTTPS configuration for local development by providing APIs to - Manage certificate trust so resources can communicate with services using self-signed certificates - Automatically handle the .NET provided ASP.NET Core development certificate (a per-user self-signed certificate valid only for local domains) across different resource types +## Trusting the ASP.NET Core development certificate + +Many of the certificate features in Aspire rely on the ASP.NET Core development certificate. Before using these features, you need to ensure that a trusted development certificate is installed on your machine. + +### Using the Aspire CLI (recommended) + +The preferred way to manage the development certificate is to use the [Aspire CLI](/get-started/install-cli/). When you run `aspire run`, the CLI automatically runs the necessary commands to ensure the development certificate is created and trusted. No additional manual steps are required. + +### Using `dotnet dev-certs` manually + +If you're not using the Aspire CLI, you need to manage the development certificate manually using the `dotnet dev-certs` tool. + +#### Trust the development certificate for the first time + +To create and trust the ASP.NET Core development certificate, run the following command: + +```bash +dotnet dev-certs https --trust +``` + +This generates a self-signed development certificate and adds it to your system's trusted certificate store. You may be prompted to confirm the trust action depending on your operating system. + +#### Refresh the development certificate + +When updating the installed .NET SDK or troubleshooting development certificate errors, it's recommended to refresh the development certificate. Newer SDK versions may include improvements or bug fixes in the generated certificate. Refreshing the certificate also avoids possible issues caused by redundant certificates being installed. + +To refresh the certificate, first clean the existing certificates and then re-trust: + +```bash +dotnet dev-certs https --clean +dotnet dev-certs https --trust +``` + + + + + ## HTTPS endpoint configuration HTTPS endpoint configuration determines which certificate a resource presents when serving HTTPS traffic. This is server-side certificate configuration for resources that host HTTPS/TLS endpoints. From 1d6375c90539ca11f0f17347cf704a615ec67838 Mon Sep 17 00:00:00 2001 From: David Negstad Date: Wed, 11 Feb 2026 11:53:21 -0800 Subject: [PATCH 2/2] Move linux trust section into main trust block. --- .../app-host/certificate-configuration.mdx | 36 +++++++++---------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/frontend/src/content/docs/app-host/certificate-configuration.mdx b/src/frontend/src/content/docs/app-host/certificate-configuration.mdx index 5ab609fc..dcfe18b2 100644 --- a/src/frontend/src/content/docs/app-host/certificate-configuration.mdx +++ b/src/frontend/src/content/docs/app-host/certificate-configuration.mdx @@ -49,24 +49,7 @@ To create and trust the ASP.NET Core development certificate, run the following dotnet dev-certs https --trust ``` -This generates a self-signed development certificate and adds it to your system's trusted certificate store. You may be prompted to confirm the trust action depending on your operating system. - -#### Refresh the development certificate - -When updating the installed .NET SDK or troubleshooting development certificate errors, it's recommended to refresh the development certificate. Newer SDK versions may include improvements or bug fixes in the generated certificate. Refreshing the certificate also avoids possible issues caused by redundant certificates being installed. - -To refresh the certificate, first clean the existing certificates and then re-trust: - -```bash -dotnet dev-certs https --clean -dotnet dev-certs https --trust -``` - - +This generates a self-signed development certificate and on Windows and MacOS adds it to your user certificate store. On Linux the certificate is stored in a well known path under your user folder. You may be prompted to confirm the trust action depending on your operating system. +#### Refresh the development certificate + +When updating the installed .NET SDK or troubleshooting development certificate errors, it's recommended to refresh the development certificate. Newer SDK versions may include improvements or bug fixes in the generated certificate. Refreshing the certificate also avoids possible issues caused by redundant certificates being installed. + +To refresh the certificate, first clean the existing certificates and then re-trust: + +```bash +dotnet dev-certs https --clean +dotnet dev-certs https --trust +``` + + + ## HTTPS endpoint configuration HTTPS endpoint configuration determines which certificate a resource presents when serving HTTPS traffic. This is server-side certificate configuration for resources that host HTTPS/TLS endpoints.