[New article]: Document the new resource certificate trust customization features

[danegsta]

Proposed topic or title

Certificate Trust Customization

Location in table of contents.

app-host > certificate-trust

Reason for the article

In Aspire 13, we're adding support for customizing what certificates resources consider trusted for TLS/HTTPS traffic. This is particularly useful for any resource that doesn't use the system's root trusted certificates by default.

We're using this feature to enable automatic trust of the ASP.NET Core Development Certificate in resources (Python and Node apps as well as containers) that wouldn't otherwise trust the certificate, which enables scenarios such as secure TLS based telemetry connections to the Aspire dashboard.

Article abstract

In Aspire 13, we're introducing the ability to customize the trusted certificates for Executable and Container resources in run mode (not currently supported in publish). Users can add their own certificate collection resources with the new CertificateAuthorityCollection resource and APIs:

var certBundle = builder.AddCertificateAuthorityCollection("my-bundle")
    .WithCertificates(myX509Certificate2Collection);

builder.AddNpmApp("my-project", "../myapp")
    .WithCertificateAuthorityCollection(certBundle);

In addition, Aspire will attempt to add trust for the ASP.NET Core Development Certificate by default (this can be overridden via app host configuration or at the per-resource level with the WithDeveloperCertificateTrust API). This will allow resources that otherwise wouldn't trust the development certificate to communicate with the Dashboard OTEL collector endpoint over HTTPS (as well as any other HTTPS endpoints secured by the development certificate).

Resources can specify the configuration required to implement certificate trust via the WithExecutableCertificateTrustCallback (for Executable resources) and WithContainerCertificateTrustCallback (for Container resources) APIs. The callbacks allows final customization of the trusted certificates as well as specifying command line arguments and environment variables required to configure trusted certificates. For container resources, various default container certificate paths can be customized as well (default values are provided that support the majority of common Linux distros, but can be overridden if necessary). Default implementations are provided for Node.js, Python, and container resources, with containers relying on standard OpenSSL configuration options.

Users can configure how custom resources are integrated with any resource default certificates by specifying a CertificateTrustScope value to the WithCertificateTrustScope API. The possible values are:

• Append: Attempts to append the configured certificates to the default trusted certificates for a given resource (not all languages, such as Python, support Append mode).
• Override: Attempts to override a resource to only trust the configured certificates.
• System (in PR): Attempts to combine the configured resources with the default system root certificates and use them to override the default trusted certificates for a resource (this is intended to support Python or other languages that don't work well with Append mode).
• None (in PR): Disable all custom certificate trust for the resource.

builder.AddPythonModule("api", "./api", "uvicorn")
    .WithCertificateTrustScope(CertificateTrustScope.Override);

Relevant searches

No response

---

Associated WorkItem - 500053