From 463fd775928f35ba3414e7d460875699c9d74ab2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 14:26:54 +0000 Subject: [PATCH 1/4] Initial plan From 1f994b890c9b57e441ef01388e1a7df3555bf922 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 14:32:25 +0000 Subject: [PATCH 2/4] Add breaking change documentation for DefaultAzureCredential in 13.0 Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- ...azurecredential-managedidentity-default.md | 100 ++++++++++++++++++ docs/compatibility/13.0/index.md | 21 ++++ docs/compatibility/toc.yml | 12 ++- 3 files changed, 132 insertions(+), 1 deletion(-) create mode 100644 docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md create mode 100644 docs/compatibility/13.0/index.md diff --git a/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md b/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md new file mode 100644 index 0000000000..ea7736b864 --- /dev/null +++ b/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md @@ -0,0 +1,100 @@ +--- +title: "Breaking change - DefaultAzureCredential defaults to ManagedIdentityCredential on ACA and App Service" +description: "Learn about the breaking change in Aspire 13.0 where DefaultAzureCredential behavior is changed to only use ManagedIdentityCredential when deploying to Azure Container Apps and Azure App Service." +ms.date: 10/17/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs-aspire/issues/5154 +--- + +# DefaultAzureCredential defaults to ManagedIdentityCredential on ACA and App Service + +In Aspire 13.0, when deploying to Azure Container Apps and Azure App Service, the default behavior of `DefaultAzureCredential` has been changed to only use `ManagedIdentityCredential`. This is accomplished by setting the `AZURE_TOKEN_CREDENTIALS` environment variable to ensure deterministic credential resolution. + +## Version introduced + +Aspire 13.0 + +## Previous behavior + +Previously, `DefaultAzureCredential` used the full chain of identity providers by default. This meant that `EnvironmentCredential` and `WorkloadIdentityCredential` would be attempted before `ManagedIdentityCredential` when authenticating to Azure resources. + +```csharp +// No explicit environment variable was set +// DefaultAzureCredential would try credentials in this order: +// 1. EnvironmentCredential +// 2. WorkloadIdentityCredential +// 3. ManagedIdentityCredential +// ... and others +``` + +## New behavior + +Now `DefaultAzureCredential` only uses `ManagedIdentityCredential` when deploying to Azure Container Apps and Azure App Service. This is achieved by setting the `AZURE_TOKEN_CREDENTIALS` environment variable automatically. + +```csharp +// The AZURE_TOKEN_CREDENTIALS environment variable is automatically set +// DefaultAzureCredential now only uses ManagedIdentityCredential +``` + +This change forces `DefaultAzureCredential` to behave in a deterministic manner and optimizes the underlying `ManagedIdentityCredential` for resilience. + +## Type of breaking change + +This is a [behavioral change](../categories.md#behavioral-change). + +## Reason for change + +This change enforces Azure SDK best practices for production environments. Using deterministic credentials improves both security and reliability by: + +- Ensuring predictable authentication behavior +- Reducing potential authentication failures from trying multiple credential types +- Optimizing credential acquisition performance +- Following the principle of least privilege by using managed identities + +For more information, see: +- [Use deterministic credentials in production environments](https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices?tabs=aspdotnet#use-deterministic-credentials-in-production-environments) +- [GitHub PR dotnet/aspire#11832](https://github.com/dotnet/aspire/pull/11832) +- [Azure SDK resilience improvements](https://github.com/Azure/azure-sdk-for-net/pull/52545) + +## Recommended action + +If you were relying on `EnvironmentCredential` or `WorkloadIdentityCredential` in your application, you can choose one of the following options to revert to the old behavior or adapt your code: + +### Option 1: Use specific credential types explicitly + +Don't use `DefaultAzureCredential` in your application. Instead, explicitly use `EnvironmentCredential` or `WorkloadIdentityCredential` in production code. + +### Option 2: Remove the environment variable in your deployment + +Implement a `PublishAsAzureContainerApp` callback and remove the environment variable from the bicep: + +```csharp +builder.AddProject("frontend") + .PublishAsAzureContainerApp((infra, app) => + { + // Remove the AZURE_TOKEN_CREDENTIALS env var to restore previous behavior + var containerAppContainer = app.Template.Containers[0].Value!; + var azureTokenCredentialEnv = containerAppContainer.Env + .Single(v => v.Value!.Name.Value == "AZURE_TOKEN_CREDENTIALS"); + containerAppContainer.Env.Remove(azureTokenCredentialEnv); + }); +``` + +For Azure App Service, use a similar approach with `PublishAsAzureAppService`: + +```csharp +builder.AddProject("frontend") + .PublishAsAzureAppService((infra, app) => + { + // Remove the AZURE_TOKEN_CREDENTIALS env var to restore previous behavior + var settings = app.Properties.SiteConfig.Value!.AppSettings!; + var azureTokenCredentialSetting = settings + .Single(s => s.Value!.Name.Value == "AZURE_TOKEN_CREDENTIALS"); + settings.Remove(azureTokenCredentialSetting); + }); +``` + +## Affected APIs + +- +- diff --git a/docs/compatibility/13.0/index.md b/docs/compatibility/13.0/index.md new file mode 100644 index 0000000000..83d040e16f --- /dev/null +++ b/docs/compatibility/13.0/index.md @@ -0,0 +1,21 @@ +--- +title: Breaking changes in Aspire 13.0 +titleSuffix: "" +description: Navigate to the breaking changes in Aspire 13.0. +ms.date: 10/17/2025 +--- + +# Breaking changes in Aspire 13.0 + +If you're migrating an app to Aspire 13.0, the breaking changes listed here might affect you. + +[!INCLUDE [binary-source-behavioral](../includes/binary-source-behavioral.md)] + +> [!NOTE] +> This article is a work in progress. It's not a complete list of breaking changes in Aspire 13.0. + +## Breaking changes + +| Title | Type of change | Introduced version | +|--|--|--| +| [DefaultAzureCredential defaults to ManagedIdentityCredential on ACA and App Service](defaultazurecredential-managedidentity-default.md) | Behavioral change | 13.0 | diff --git a/docs/compatibility/toc.yml b/docs/compatibility/toc.yml index b0a1e43590..5aab5c8c93 100644 --- a/docs/compatibility/toc.yml +++ b/docs/compatibility/toc.yml @@ -5,9 +5,19 @@ items: href: ../get-started/aspire-overview.md - name: Breaking changes href: breaking-changes.md -- name: Aspire 9.5 +- name: Aspire 13.0 expanded: true items: + - name: Overview + href: 13.0/index.md + - name: Breaking changes in 13.0 + expanded: true + items: + - name: DefaultAzureCredential defaults to ManagedIdentityCredential on ACA and App Service + href: 13.0/defaultazurecredential-managedidentity-default.md +- name: Aspire 9.5 + expanded: false + items: - name: Overview href: 9.5/index.md - name: Breaking changes in 9.5 From c11a5b7e27b3f1fb3946642588962cf4c8be2d59 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 17 Oct 2025 14:33:53 +0000 Subject: [PATCH 3/4] Fix markdown linting error - add blank line before list Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com> --- .../13.0/defaultazurecredential-managedidentity-default.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md b/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md index ea7736b864..891345e394 100644 --- a/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md +++ b/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md @@ -52,6 +52,7 @@ This change enforces Azure SDK best practices for production environments. Using - Following the principle of least privilege by using managed identities For more information, see: + - [Use deterministic credentials in production environments](https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices?tabs=aspdotnet#use-deterministic-credentials-in-production-environments) - [GitHub PR dotnet/aspire#11832](https://github.com/dotnet/aspire/pull/11832) - [Azure SDK resilience improvements](https://github.com/Azure/azure-sdk-for-net/pull/52545) From 97debb2ed7c8c46f03b3ddcb15b662a3409209b1 Mon Sep 17 00:00:00 2001 From: David Pine Date: Fri, 17 Oct 2025 10:41:25 -0500 Subject: [PATCH 4/4] Update docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md --- .../13.0/defaultazurecredential-managedidentity-default.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md b/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md index 891345e394..53500b6d25 100644 --- a/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md +++ b/docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md @@ -97,5 +97,5 @@ builder.AddProject("frontend") ## Affected APIs -- -- +- +-