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 924c7339f..85ecdd4ec 100644 --- a/src/frontend/src/content/docs/app-host/certificate-configuration.mdx +++ b/src/frontend/src/content/docs/app-host/certificate-configuration.mdx @@ -73,11 +73,13 @@ aspire certs trust You may need to reload your profile or start a new terminal session for the change to take effect. -### Developer certificate for DCP communication (Windows) +### Developer certificate for DCP communication -By default, Aspire's internal Developer Control Plane (DCP) server uses an ephemeral localhost certificate it generates itself for TLS. On Windows, you can opt in to using your trusted Aspire developer certificate for DCP communication instead, which avoids trust issues caused by the ephemeral certificate not being in the system trust store. +By default, Aspire uses the ASP.NET Core developer certificate to secure communication with its internal Developer Control Plane (DCP) server. This replaces the ephemeral localhost certificate that DCP would otherwise generate itself, and avoids certificate trust errors caused by that certificate not being in the system trust store. -Set the `ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE` environment variable to `true` in your AppHost's `launchSettings.json` or as a system/user environment variable: +If no trusted developer certificate is found, Aspire automatically falls back to DCP's ephemeral certificate. + +To opt out and use DCP's default ephemeral certificate instead, set `ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE` to `false` in your AppHost's `launchSettings.json` or as an environment variable: ```json title="Properties/launchSettings.json" { @@ -85,23 +87,17 @@ Set the `ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE` environment variable to `true` in "https": { "commandName": "Project", "environmentVariables": { - "ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE": "true" + "ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE": "false" } } } } ``` -When this setting is enabled: - -- Aspire checks for a trusted developer certificate. -- If a trusted certificate is found, it is used to secure the DCP server. -- If no trusted certificate is found, Aspire falls back to the DCP-generated ephemeral certificate. -- This setting is only supported on Windows. On other platforms, a warning is logged and DCP falls back to its default ephemeral certificate. - ## HTTPS endpoint configuration diff --git a/src/frontend/src/content/docs/app-host/configuration.mdx b/src/frontend/src/content/docs/app-host/configuration.mdx index bc99fef40..c66c3dc32 100644 --- a/src/frontend/src/content/docs/app-host/configuration.mdx +++ b/src/frontend/src/content/docs/app-host/configuration.mdx @@ -80,7 +80,7 @@ In TypeScript AppHosts, profiles live in `aspire.config.json`: | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ASPIRE_ALLOW_UNSECURED_TRANSPORT` | `false` | Allows communication with the AppHost without https. `ASPNETCORE_URLS` (dashboard address) and `ASPIRE_RESOURCE_SERVICE_ENDPOINT_URL` (AppHost resource service address) must be secured with HTTPS unless true. | | `ASPIRE_CONTAINER_RUNTIME` | `docker` | Allows the user of alternative container runtimes for resources backed by containers. Possible values are `docker` (default) or `podman`. | -| `ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE` | `false` | When set to `true`, Aspire uses its trusted developer certificate to secure the internal DCP server instead of an ephemeral certificate generated by DCP. This can help avoid certificate trust issues when the dev cert is already trusted. If no trusted developer certificate is found, Aspire falls back to the DCP-generated ephemeral certificate. Only supported on Windows. For more information, see [Certificate configuration](/app-host/certificate-configuration/). | +| `ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE` | `true` | When `true` (the default), Aspire uses the ASP.NET Core developer certificate to secure the internal DCP server instead of an ephemeral certificate generated by DCP. On Windows, Aspire passes the certificate thumbprint to DCP. On macOS and Linux, Aspire passes the certificate and private key file paths (plus the thumbprint) so DCP can verify the loaded certificate. Set to `false` to opt out and use DCP's default ephemeral certificate. If no trusted developer certificate is found, Aspire automatically falls back to the ephemeral certificate. For more information, see [Certificate configuration](/app-host/certificate-configuration/). | | `ASPIRE_ENVIRONMENT` | `null` | Configures the AppHost environment when no higher-priority environment source is set. If no environment is configured, the AppHost uses `Production`. | | `ASPIRE_VERSION_CHECK_DISABLED` | `false` | When set to `true`, Aspire doesn't check for newer versions on startup. |