Skip to content

Commit 32c19fa

Browse files
CopilotIEvangelist
Copilot
and
IEvangelist
authored
Add certificate trust customization article for Aspire 13 (#5311)
* Initial plan * Add certificate trust customization article Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> * Fix cross-reference title to match actual article title Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> * Address PR feedback: update API examples, add runtime callout, document default scopes Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> * Update callback APIs to use async Task and simplified context objects Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> * Replace deprecated callback APIs with new simplified APIs Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
1 parent 4175ee9 commit 32c19fa

File tree

2 files changed

+284
-0
lines changed

2 files changed

+284
-0
lines changed

‎docs/app-host/certificate-trust.md‎

Lines changed: 281 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,281 @@
1+
---
2+
title: Certificate trust customization in Aspire
3+
description: Learn how to customize trusted certificates for Executable and Container resources in Aspire to enable secure communication.
4+
ms.date: 10/20/2025
5+
ai-usage: ai-assisted
6+
---
7+
8+
# Certificate trust customization in Aspire
9+
10+
In Aspire, you can customize which certificates resources consider trusted for TLS/HTTPS traffic. This is particularly useful for resources that don't use the system's root trusted certificates by default, such as containerized applications, Python apps, and Node.js apps. By configuring certificate trust, you enable these resources to communicate securely with services that use certificates they wouldn't otherwise trust, including the Aspire dashboard's OTLP endpoint.
11+
12+
> [!IMPORTANT]
13+
> Certificate trust customization only applies at run time. Custom certificates aren't included in publish or deployment artifacts.
14+
15+
## When to use certificate trust customization
16+
17+
Certificate trust customization is valuable when:
18+
19+
- Resources need to trust the ASP.NET Core Development Certificate for local HTTPS communication.
20+
- Containerized services must communicate with the dashboard over HTTPS.
21+
- Python or Node.js applications need to trust custom certificate authorities.
22+
- You're working with services that have specific certificate trust requirements.
23+
- Resources need to establish secure telemetry connections to the Aspire dashboard.
24+
25+
## Development certificate trust
26+
27+
By default, Aspire attempts to add trust for the ASP.NET Core Development Certificate to resources that wouldn't otherwise trust it. This enables resources to communicate with the dashboard OTEL collector endpoint over HTTPS and any other HTTPS endpoints secured by the development certificate.
28+
29+
You can control this behavior at the per-resource level using the `WithDeveloperCertificateTrust` API or through AppHost configuration settings.
30+
31+
### Configure development certificate trust per resource
32+
33+
To explicitly enable or disable development certificate trust for a specific resource:
34+
35+
```csharp
36+
var builder = DistributedApplication.CreateBuilder(args);
37+
38+
// Explicitly enable development certificate trust
39+
var nodeApp = builder.AddNpmApp("frontend", "../frontend")
40+
.WithDeveloperCertificateTrust(trust: true);
41+
42+
// Disable development certificate trust
43+
var pythonApp = builder.AddPythonApp("api", "../api", "main.py")
44+
.WithDeveloperCertificateTrust(trust: false);
45+
46+
builder.Build().Run();
47+
```
48+
49+
## Certificate authority collections
50+
51+
Certificate authority collections allow you to bundle custom certificates and make them available to resources. You create a collection using the `AddCertificateAuthorityCollection` method and then reference it from resources that need to trust those certificates.
52+
53+
### Create and use a certificate authority collection
54+
55+
```csharp
56+
using System.Security.Cryptography.X509Certificates;
57+
58+
var builder = DistributedApplication.CreateBuilder(args);
59+
60+
// Load your custom certificates
61+
var certificates = new X509Certificate2Collection();
62+
certificates.ImportFromPemFile("path/to/certificate.pem");
63+
64+
// Create a certificate authority collection
65+
var certBundle = builder.AddCertificateAuthorityCollection("my-bundle")
66+
.WithCertificates(certificates);
67+
68+
// Apply the certificate bundle to resources
69+
builder.AddNpmApp("my-project", "../myapp")
70+
.WithCertificateAuthorityCollection(certBundle);
71+
72+
builder.Build().Run();
73+
```
74+
75+
In the preceding example, the certificate bundle is created with custom certificates and then applied to a Node.js application, enabling it to trust those certificates.
76+
77+
## Certificate trust scopes
78+
79+
Certificate trust scopes control how custom certificates interact with a resource's default trusted certificates. Different scopes provide flexibility in managing certificate trust based on your application's requirements.
80+
81+
The `WithCertificateTrustScope` API accepts a <xref:Aspire.Hosting.ApplicationModel.CertificateTrustScope> value to specify the trust behavior.
82+
83+
### Default trust scopes
84+
85+
Different resource types have different default trust scopes:
86+
87+
- **Append**: The default for most resources, appending custom certificates to the default trusted certificates.
88+
- **System**: The default for Python projects, which combines custom certificates with system root certificates because Python doesn't properly support Append mode.
89+
- **None**: The default for .NET projects on Windows, as there's no way to automatically change the default system store source.
90+
91+
### Append mode
92+
93+
Attempts to append the configured certificates to the default trusted certificates for a given resource. This mode is useful when you want to add trust for additional certificates while maintaining trust for the system's default certificates.
94+
95+
```csharp
96+
var builder = DistributedApplication.CreateBuilder(args);
97+
98+
builder.AddNodeApp("api", "../api")
99+
.WithCertificateTrustScope(CertificateTrustScope.Append);
100+
101+
builder.Build().Run();
102+
```
103+
104+
> [!NOTE]
105+
> Not all languages and runtimes support Append mode. For example, Python doesn't natively support appending certificates to the default trust store.
106+
107+
### Override mode
108+
109+
Attempts to override a resource to only trust the configured certificates, replacing the default trusted certificates entirely. This mode is useful when you need strict control over which certificates are trusted.
110+
111+
```csharp
112+
var builder = DistributedApplication.CreateBuilder(args);
113+
114+
var certBundle = builder.AddCertificateAuthorityCollection("custom-certs")
115+
.WithCertificates(myCertificates);
116+
117+
builder.AddPythonModule("api", "./api", "uvicorn")
118+
.WithCertificateAuthorityCollection(certBundle)
119+
.WithCertificateTrustScope(CertificateTrustScope.Override);
120+
121+
builder.Build().Run();
122+
```
123+
124+
### System mode
125+
126+
Attempts to combine the configured certificates with the default system root certificates and use them to override the default trusted certificates for a resource. This mode is intended to support Python or other languages that don't work well with Append mode.
127+
128+
```csharp
129+
var builder = DistributedApplication.CreateBuilder(args);
130+
131+
builder.AddPythonApp("worker", "../worker", "main.py")
132+
.WithCertificateTrustScope(CertificateTrustScope.System);
133+
134+
builder.Build().Run();
135+
```
136+
137+
### None mode
138+
139+
Disables all custom certificate trust for the resource, causing it to rely solely on its default certificate trust behavior.
140+
141+
```csharp
142+
var builder = DistributedApplication.CreateBuilder(args);
143+
144+
builder.AddContainer("service", "myimage")
145+
.WithCertificateTrustScope(CertificateTrustScope.None);
146+
147+
builder.Build().Run();
148+
```
149+
150+
## Custom certificate trust configuration
151+
152+
For advanced scenarios, you can specify custom certificate trust behavior using a callback API. This callback allows you to customize the command line arguments and environment variables required to configure certificate trust for different resource types.
153+
154+
### Configure certificate trust with a callback
155+
156+
Use `WithCertificateTrustConfiguration` to customize how certificate trust is configured for a resource:
157+
158+
```csharp
159+
var builder = DistributedApplication.CreateBuilder(args);
160+
161+
builder.AddContainer("api", "myimage")
162+
.WithCertificateTrustConfiguration(async (ctx) =>
163+
{
164+
// Add a command line argument
165+
ctx.Arguments.Add("--use-system-ca");
166+
167+
// Set environment variables with certificate paths
168+
// CertificateBundlePath resolves to the path of the custom certificate bundle file
169+
ctx.EnvironmentVariables["MY_CUSTOM_CERT_VAR"] = ctx.CertificateBundlePath;
170+
171+
// CertificateDirectoriesPath resolves to paths containing individual certificates
172+
ctx.EnvironmentVariables["CERTS_DIR"] = ctx.CertificateDirectoriesPath;
173+
174+
await Task.CompletedTask;
175+
});
176+
177+
builder.Build().Run();
178+
```
179+
180+
The callback receives a `CertificateTrustConfigurationCallbackAnnotationContext` that provides:
181+
182+
- `Scope`: The `CertificateTrustScope` for the resource.
183+
- `Arguments`: Command line arguments for the resource. Values can be strings or path providers like `CertificateBundlePath` or `CertificateDirectoriesPath`.
184+
- `EnvironmentVariables`: Environment variables for configuring certificate trust. The dictionary key is the environment variable name; values can be strings or path providers. By default, includes `SSL_CERT_DIR` and may include `SSL_CERT_FILE` if Override or System scope is configured.
185+
- `CertificateBundlePath`: A value provider that resolves to the path of a custom certificate bundle file.
186+
- `CertificateDirectoriesPath`: A value provider that resolves to paths containing individual certificates.
187+
188+
Default implementations are provided for Node.js, Python, and container resources. Container resources rely on standard OpenSSL configuration options, with default values that support the majority of common Linux distributions.
189+
190+
### Configure container certificate paths
191+
192+
For container resources, you can customize where certificates are stored and accessed using `WithContainerCertificatePaths`:
193+
194+
```csharp
195+
var builder = DistributedApplication.CreateBuilder(args);
196+
197+
builder.AddContainer("api", "myimage")
198+
.WithContainerCertificatePaths(
199+
customCertificatesDestination: "/custom/certs/path",
200+
defaultCertificateBundlePaths: ["/etc/ssl/certs/ca-certificates.crt"],
201+
defaultCertificateDirectoryPaths: ["/etc/ssl/certs"]);
202+
203+
builder.Build().Run();
204+
```
205+
206+
The `WithContainerCertificatePaths` API accepts three optional parameters:
207+
208+
- `customCertificatesDestination`: Overrides the base path in the container where custom certificate files are placed. If not set or set to `null`, the default path of `/usr/lib/ssl/aspire` is used.
209+
- `defaultCertificateBundlePaths`: Overrides the path(s) in the container where a default certificate authority bundle file is located. When the `CertificateTrustScope` is Override or System, the custom certificate bundle is additionally written to these paths. If not set or set to `null`, a set of default certificate paths for common Linux distributions is used.
210+
- `defaultCertificateDirectoryPaths`: Overrides the path(s) in the container where individual trusted certificate files are found. When the `CertificateTrustScope` is Append, these paths are concatenated with the path to the uploaded certificate artifacts. If not set or set to `null`, a set of default certificate paths for common Linux distributions is used.
211+
212+
> [!NOTE]
213+
> All desired paths must be configured in a single call to `WithContainerCertificatePaths` as only the most recent call to the API is honored.
214+
215+
## Common scenarios
216+
217+
### Enable HTTPS telemetry to the dashboard
218+
219+
By default, Aspire enables development certificate trust for resources, allowing them to send telemetry to the dashboard over HTTPS:
220+
221+
```csharp
222+
var builder = DistributedApplication.CreateBuilder(args);
223+
224+
// Development certificate trust is enabled by default
225+
var nodeApp = builder.AddNpmApp("frontend", "../frontend");
226+
var pythonApp = builder.AddPythonApp("api", "../api", "main.py");
227+
228+
builder.Build().Run();
229+
```
230+
231+
### Trust custom certificates in containers
232+
233+
When working with containerized services that need to trust custom certificates:
234+
235+
```csharp
236+
using System.Security.Cryptography.X509Certificates;
237+
238+
var builder = DistributedApplication.CreateBuilder(args);
239+
240+
// Load custom CA certificates
241+
var customCerts = new X509Certificate2Collection();
242+
customCerts.Import("corporate-ca.pem");
243+
244+
var certBundle = builder.AddCertificateAuthorityCollection("corporate-certs")
245+
.WithCertificates(customCerts);
246+
247+
// Apply to container
248+
builder.AddContainer("service", "myservice:latest")
249+
.WithCertificateAuthorityCollection(certBundle);
250+
251+
builder.Build().Run();
252+
```
253+
254+
### Disable certificate trust for Python apps
255+
256+
Python projects use System mode by default. To disable certificate trust customization for a Python app:
257+
258+
```csharp
259+
var builder = DistributedApplication.CreateBuilder(args);
260+
261+
// Disable certificate trust for Python apps
262+
builder.AddPythonModule("api", "./api", "uvicorn")
263+
.WithCertificateTrustScope(CertificateTrustScope.None);
264+
265+
builder.Build().Run();
266+
```
267+
268+
## Limitations
269+
270+
Certificate trust customization has the following limitations:
271+
272+
- Currently supported only in run mode, not in publish mode.
273+
- Not all languages and runtimes support all trust scope modes.
274+
- Python applications don't natively support Append mode.
275+
- Custom certificate trust requires appropriate runtime support within the resource.
276+
277+
## See also
278+
279+
- [Host external executables in Aspire](executable-resources.md)
280+
- [Add Dockerfiles to your .NET app model](withdockerfile.md)
281+
- [AppHost configuration](configuration.md)

‎docs/toc.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,9 @@ items:
5757
href: get-started/build-aspire-apps-with-python.md
5858
- name: AppHost configuration
5959
href: app-host/configuration.md
60+
- name: Certificate trust customization
61+
href: app-host/certificate-trust.md
62+
displayName: certificate trust,TLS,HTTPS,development certificate,certificate authority
6063
- name: Customize resources
6164
items:
6265
- name: Persistent container services

0 commit comments

Comments
 (0)