From 7305329ba4c31e6e09fdd0a30d323b3b14a30536 Mon Sep 17 00:00:00 2001 From: Eric Erhardt Date: Mon, 28 Sep 2026 10:43:35 -0500 Subject: [PATCH] Document MongoDB automatic TLS migration in Aspire 13.6 Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../databases/mongodb/mongodb-connect.mdx | 16 ++- .../databases/mongodb/mongodb-host.mdx | 122 +++++++++++++++++- .../content/docs/whats-new/aspire-13-6.mdx | 20 ++- 3 files changed, 152 insertions(+), 6 deletions(-) diff --git a/src/frontend/src/content/docs/integrations/databases/mongodb/mongodb-connect.mdx b/src/frontend/src/content/docs/integrations/databases/mongodb/mongodb-connect.mdx index ff11a1b0e..e66314603 100644 --- a/src/frontend/src/content/docs/integrations/databases/mongodb/mongodb-connect.mdx +++ b/src/frontend/src/content/docs/integrations/databases/mongodb/mongodb-connect.mdx @@ -38,14 +38,22 @@ The MongoDB server resource exposes the following connection properties: | `Password` | The password for authentication | | `AuthenticationDatabase` | The authentication database (when credentials are configured) | | `AuthenticationMechanism` | The authentication mechanism (when credentials are configured) | -| `Uri` | The connection URI, with the format `mongodb://{Username}:{Password}@{Host}:{Port}/?authSource={AuthenticationDatabase}&authMechanism={AuthenticationMechanism}` | +| `Uri` | The connection URI, with the format `mongodb://{Username}:{Password}@{Host}:{Port}/?authSource={AuthenticationDatabase}&authMechanism={AuthenticationMechanism}&tls=true` | -**Example connection string:** +Starting in Aspire 13.6, ordinary MongoDB server resources use TLS during local runs when a certificate is configured and available. Consume the complete generated URI rather than reconstructing it from `Host` and `Port`, which omit TLS and other connection options. Your client must also trust the certificate and connect using a hostname it covers; trusting the certificate alone doesn't resolve a hostname mismatch for container clients. See [Automatic TLS and migration](../mongodb-host/#automatic-tls-and-migration-from-earlier-versions) for certificate requirements and local-development options. + +**Example connection string without TLS:** ``` Uri: mongodb://admin:p%40ssw0rd1@localhost:27017/?authSource=admin&authMechanism=SCRAM-SHA-256 ``` +**Example connection string with TLS enabled:** + +```text title="MongoDB server URI (credentials redacted)" +mongodb://:@localhost:27017/?authSource=admin&authMechanism=SCRAM-SHA-256&tls=true +``` + ### MongoDB database The MongoDB database resource inherits all properties from its parent server resource and adds: @@ -54,7 +62,9 @@ The MongoDB database resource inherits all properties from its parent server res | -------------- | ----------- | | `DatabaseName` | The MongoDB database name | -**Example:** +The database's generated URI also includes `tls=true` when its parent server uses TLS. Preserve this option when passing the URI to your client. + +**Example without TLS:** ``` Uri: mongodb://admin:p%40ssw0rd1@localhost:27017/?authSource=admin&authMechanism=SCRAM-SHA-256 diff --git a/src/frontend/src/content/docs/integrations/databases/mongodb/mongodb-host.mdx b/src/frontend/src/content/docs/integrations/databases/mongodb/mongodb-host.mdx index d81e346d1..6a7019d3d 100644 --- a/src/frontend/src/content/docs/integrations/databases/mongodb/mongodb-host.mdx +++ b/src/frontend/src/content/docs/integrations/databases/mongodb/mongodb-host.mdx @@ -134,6 +134,122 @@ If you'd rather connect to an existing MongoDB server, call `AddConnectionString +## Automatic TLS and migration from earlier versions + +Starting in **Aspire 13.6**, MongoDB participates in Aspire's shared certificate configuration during local runs. This applies to ordinary `AddMongoDB` / `addMongoDB` resources, **not just replica sets**. When a certificate is configured and available, normally the ASP.NET Core developer certificate under the default settings, Aspire starts MongoDB with `--tlsMode requireTLS` and adds `tls=true` to its generated connection string. Without an available configured certificate, the standalone server uses plaintext. + +Existing clients that connected without TLS can stop working after upgrading. Use the **complete Aspire-generated connection string**, such as the `MONGODB_URI` environment variable for a database resource named `mongodb`, rather than rebuilding a URI from `Host` and `Port`. The generated URI preserves TLS and other connection options, but clients still need to validate the server certificate. + +### Certificate trust and hostname validation + +A successful TLS connection requires both: + +- **Certificate trust**: The client trusts the server certificate or its issuing certificate authority. +- **Hostname validation**: The hostname used to connect matches a name in the server certificate. + +A client running directly on the host can connect through the generated `localhost` endpoint using the developer certificate, provided the client's runtime trusts that certificate. A client running in a container typically reaches MongoDB by its resource name, such as `mongo`. That name isn't covered by the default developer certificate, so trusting the certificate alone doesn't fix the hostname mismatch. + +For container-to-container TLS, configure a server certificate whose subject alternative names cover the actual connection hostnames, and configure the client to trust its issuing authority. C# AppHosts can supply a custom certificate with `WithHttpsCertificate`; this API isn't available in TypeScript AppHosts. Alternatively, run the consuming app directly on the host with a trusted localhost certificate, or explicitly choose the local-development opt-out below for a standalone or simple single-member server. Don't use disabled certificate or hostname validation as a general migration solution. + + + See [Certificate configuration](/app-host/certificate-configuration/) for + developer-certificate trust and custom server certificates. + + +### Opt out for one local MongoDB server + +If you need plaintext connections for local development, opt out on the MongoDB resource rather than changing certificate defaults for the whole AppHost: + + + + +```typescript title="apphost.mts" twoslash +import { createBuilder } from './.aspire/modules/aspire.mjs'; + +const builder = await createBuilder(); + +const mongo = await builder.addMongoDB("mongo"); +await mongo.withoutHttpsCertificate(); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +#pragma warning disable ASPIRECERTIFICATES001 +var mongo = builder.AddMongoDB("mongo") + .WithoutHttpsCertificate(); +#pragma warning restore ASPIRECERTIFICATES001 + +builder.Build().Run(); +``` + + + + +The certificate API is experimental and reports [ASPIRECERTIFICATES001](/diagnostics/aspirecertificates001/) in C#. This opt-out also works when the server uses the [simple single-member replica-set configuration](#enable-transactions-and-change-streams-with-a-single-member-replica-set): configure `WithReplicaSet()` / `withReplicaSet()` on the same server. That path doesn't require TLS. + +:::caution +This opt-out disables transport encryption. Use it only as an explicit local-development choice, not as a production security configuration. Don't apply it to members of an advanced `AddMongoDBReplicaSet(...).WithMember(...)` configuration, which requires TLS. +::: + +### Allow plaintext and TLS clients + +To accept both plaintext and TLS connections while retaining the server's certificate configuration, select `PreferTls`: + + + + +```typescript title="apphost.mts" twoslash +import { createBuilder, MongoDBTlsMode } from './.aspire/modules/aspire.mjs'; + +const builder = await createBuilder(); + +const mongo = await builder.addMongoDB("mongo"); +await mongo.withTlsMode({ mode: MongoDBTlsMode.PreferTls }); + +await builder.build().run(); +``` + + + + +```csharp title="AppHost.cs" +var builder = DistributedApplication.CreateBuilder(args); + +#pragma warning disable ASPIREMONGODB001 +var mongo = builder.AddMongoDB("mongo") + .WithTlsMode(MongoDBTlsMode.PreferTls); +#pragma warning restore ASPIREMONGODB001 + +builder.Build().Run(); +``` + + + + +This experimental API controls how the server accepts connections **when TLS is active**; it doesn't enable TLS without a certificate. The generated connection string still includes `tls=true`, so consumers using it still need certificate trust and a matching hostname. `PreferTls` isn't equivalent to disabling TLS, and allowing plaintext clients leaves those connections unencrypted. + +### Global defaults and replica-set limits + +Set `ASPIRE_DEVELOPER_CERTIFICATE_DEFAULT_HTTPS_TERMINATION=false` in the **AppHost's environment** to disable ambient developer-certificate server defaults globally. This affects other resources as well as MongoDB. Prefer the resource-level opt-out when only MongoDB needs different behavior. The global switch doesn't remove explicit certificate configuration. + +| MongoDB configuration | Local TLS behavior | +| --------------------- | ------------------ | +| Standalone `AddMongoDB` / `addMongoDB` | Uses automatic TLS when a certificate is configured and available; supports the resource-level opt-out. | +| Simple `WithReplicaSet` / `withReplicaSet` on a server | Preserves the server's automatic TLS behavior; supports the same opt-out without requiring TLS or split-horizon discovery. | +| Advanced `AddMongoDBReplicaSet(...).WithMember(...)` | Explicitly configures developer certificates unless a member already has certificate configuration. Requires TLS and Server Name Indication (SNI) for split-horizon discovery; don't use the no-TLS workaround. | + +The advanced path is for local multi-member experiments. Disabling ambient defaults doesn't disable its explicit certificate configuration, and initialization fails if a member has no TLS. Its certificate requirements aren't a reason to disable validation in application clients. + +### Run versus publish + +Automatic developer-certificate configuration applies to **local run mode**. Published MongoDB containers don't automatically receive the same certificate configuration; configure production transport security for your deployment separately. Both replica-set paths, keyfile configuration, and explicit MongoDB TLS configuration APIs such as `WithTlsMode` reject publish mode because their deployment support hasn't been implemented. + ## Add MongoDB server resource with parameters When you want to explicitly provide the username and password used by the container image, you can provide these credentials as parameters: @@ -404,7 +520,7 @@ await builder.addNodeApp("api", "./api", "index.js") -Omit `WithReplicaSet` / `withReplicaSet` when a standalone server is sufficient — plain MongoDB and its automatic TLS behavior are unchanged. +Omit `WithReplicaSet` / `withReplicaSet` when a standalone server is sufficient. Both configurations use the [automatic TLS behavior introduced in Aspire 13.6](#automatic-tls-and-migration-from-earlier-versions); the simple single-member path doesn't require TLS and supports the same local-development opt-out. The replica set's name is optional and defaults to the server's Aspire resource name. Pass an explicit name to override it: @@ -552,6 +668,10 @@ await mongo.withLifetime("Persistent"); By default, Aspire injects the MongoDB connection information using variable names derived from the resource name (for example, `MONGODB_URI`, `MONGODB_HOST`, `MONGODB_PORT`). If your consuming app expects a different set of environment variable names, pass individual connection properties from the AppHost: +:::caution +The individual properties below aren't a replacement for the complete generated URI. Rebuilding a URI from host and port can omit `tls=true` and other required options. Prefer the generated `MONGODB_URI`; if your client requires separate settings, also configure its TLS and certificate validation to match the server. See [Automatic TLS and migration](#automatic-tls-and-migration-from-earlier-versions). +::: + ```csharp title="AppHost.cs" diff --git a/src/frontend/src/content/docs/whats-new/aspire-13-6.mdx b/src/frontend/src/content/docs/whats-new/aspire-13-6.mdx index 3f358127a..9b5c78a4e 100644 --- a/src/frontend/src/content/docs/whats-new/aspire-13-6.mdx +++ b/src/frontend/src/content/docs/whats-new/aspire-13-6.mdx @@ -48,7 +48,7 @@ This release introduces: - **Updated emulator images** — move Azure App Configuration to `1.2.0` and make the Linux-based vNext Cosmos DB emulator the default. - **Bug fixes** — improvements across orchestration, debugging, telemetry, and deployment. - **Community contributions** — contributions span major features, integration improvements, reliability fixes, and project tooling. -- **Breaking changes** — review Cosmos DB emulator defaults, Front Door origin names, portable connection-string aliases, and the experimental terminal namespace move. +- **Breaking changes** — review MongoDB automatic TLS, Cosmos DB emulator defaults, Front Door origin names, portable connection-string aliases, and the experimental terminal namespace move. - …and much more. ## 🆙 Upgrade to Aspire 13.6 @@ -58,7 +58,7 @@ This release introduces: @@ -507,6 +507,7 @@ Existing integrations add new workflows and safer defaults: - **Deno hosting.** `Aspire.Hosting.JavaScript` adds `AddDenoApp` / `addDenoApp`, with task and serve modes, permission controls, and runtime flags. Deno must be installed for local execution. See [Deno hosting](/integrations/frameworks/deno/deno-host/). - **MongoDB replica sets.** Experimental `WithReplicaSet` / `withReplicaSet` configures and initializes a single-member replica set, enabling transactions and change streams after readiness. A separate `AddMongoDBReplicaSet` API supports multi-member local scenarios. Both paths are local-run-only and reject publishing; see [MongoDB replica sets](/integrations/databases/mongodb/mongodb-host/#enable-transactions-and-change-streams-with-a-single-member-replica-set). +- **MongoDB automatic TLS.** Local MongoDB resources now use Aspire's shared certificate configuration, including standalone servers. Existing plaintext clients should review the [TLS migration guidance](#mongodb-now-uses-automatic-tls-during-local-runs). - **Microsoft Foundry Toolboxes.** `AddToolbox` / `addToolbox` bundles tools behind one MCP endpoint and manages immutable versions as tool configuration changes. MCP approval policies are discovery metadata that the consuming application must enforce. See the [Toolbox integration guide](https://github.com/microsoft/aspire/blob/a11eca9611073f7cf66fa87faac63c2119e87713/src/Aspire.Hosting.Foundry/README.md#toolbox-usage). - **Blazor WebAssembly debugging.** Standalone and hosted WebAssembly apps can expose dashboard commands for starting and stopping an Edge or Chrome debugging session. The related Dotnet project gateway APIs are also available to polyglot AppHosts, but remain experimental and run-only. - **Dev Tunnel discovery and expiration.** Tunnel, inspect, and local endpoint URLs appear as highlighted resource properties, and a **Show tunnel URLs** command surfaces them through the dashboard Interaction Service. `WithExpiration` / `withExpiration` also configures idle expiration for new or reused tunnels, in whole hours from one hour through 30 days. @@ -557,6 +558,21 @@ Aspire is built in the open, and this release wouldn't be what it is without you +#### MongoDB now uses automatic TLS during local runs + +Starting in Aspire 13.6, MongoDB server resources participate in shared certificate configuration. When a certificate is configured and available, normally the developer certificate under default settings, Aspire starts the server with `--tlsMode requireTLS` and adds `tls=true` to its generated connection string. This changes the previous plaintext default for **ordinary `AddMongoDB` resources**, even if you don't use replica sets. + +Use the complete generated connection string instead of constructing a URI from host and port. Clients must trust the server certificate and use a hostname it covers. A container client connecting by the MongoDB resource name can encounter a hostname mismatch with the developer certificate; trusting the certificate alone doesn't fix that. + +For an explicit local-development opt-out, use `WithoutHttpsCertificate()` / `withoutHttpsCertificate()` on a standalone server or the simple `WithReplicaSet()` / `withReplicaSet()` configuration. This disables transport encryption. Don't apply it to advanced `AddMongoDBReplicaSet(...).WithMember(...)` members, which require TLS/SNI for split-horizon discovery. + +`PreferTls` accepts plaintext and TLS clients but still advertises TLS in generated connection strings. The global `ASPIRE_DEVELOPER_CERTIFICATE_DEFAULT_HTTPS_TERMINATION=false` switch affects ambient defaults for other resources too; it doesn't disable explicit member certificates. These local-run defaults don't automatically configure certificates for published MongoDB containers. + + + See [MongoDB automatic TLS and migration](/integrations/databases/mongodb/mongodb-host/#automatic-tls-and-migration-from-earlier-versions) + for C# and TypeScript examples, certificate arrangements, and the limits of each option. + + #### Azure Cosmos DB now defaults to the Linux-based vNext emulator `RunAsEmulator` / `runAsEmulator` now selects the `vnext-latest` Linux-based emulator instead of the `stable` classic emulator. To keep the previous behavior, switch to `RunAsClassicEmulator` / `runAsClassicEmulator`: