Skip to content

Commit bea2f8e

Browse files
CopilotIEvangelist
Copilot
and
IEvangelist
authored
Document breaking change: DefaultAzureCredential defaults to ManagedIdentityCredential on ACA and App Service (#5303)
* Initial plan * Add breaking change documentation for DefaultAzureCredential in 13.0 Co-authored-by: IEvangelist <[email protected]> * Fix markdown linting error - add blank line before list Co-authored-by: IEvangelist <[email protected]> * Update docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: IEvangelist <[email protected]> Co-authored-by: David Pine <[email protected]>
1 parent 5f42178 commit bea2f8e

File tree

3 files changed

+133
-1
lines changed

3 files changed

+133
-1
lines changed

‎docs/compatibility/13.0/defaultazurecredential-managedidentity-default.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: "Breaking change - DefaultAzureCredential defaults to ManagedIdentityCredential on ACA and App Service"
3+
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."
4+
ms.date: 10/17/2025
5+
ai-usage: ai-assisted
6+
ms.custom: https://github.com/dotnet/docs-aspire/issues/5154
7+
---
8+
9+
# DefaultAzureCredential defaults to ManagedIdentityCredential on ACA and App Service
10+
11+
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.
12+
13+
## Version introduced
14+
15+
Aspire 13.0
16+
17+
## Previous behavior
18+
19+
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.
20+
21+
```csharp
22+
// No explicit environment variable was set
23+
// DefaultAzureCredential would try credentials in this order:
24+
// 1. EnvironmentCredential
25+
// 2. WorkloadIdentityCredential
26+
// 3. ManagedIdentityCredential
27+
// ... and others
28+
```
29+
30+
## New behavior
31+
32+
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.
33+
34+
```csharp
35+
// The AZURE_TOKEN_CREDENTIALS environment variable is automatically set
36+
// DefaultAzureCredential now only uses ManagedIdentityCredential
37+
```
38+
39+
This change forces `DefaultAzureCredential` to behave in a deterministic manner and optimizes the underlying `ManagedIdentityCredential` for resilience.
40+
41+
## Type of breaking change
42+
43+
This is a [behavioral change](../categories.md#behavioral-change).
44+
45+
## Reason for change
46+
47+
This change enforces Azure SDK best practices for production environments. Using deterministic credentials improves both security and reliability by:
48+
49+
- Ensuring predictable authentication behavior
50+
- Reducing potential authentication failures from trying multiple credential types
51+
- Optimizing credential acquisition performance
52+
- Following the principle of least privilege by using managed identities
53+
54+
For more information, see:
55+
56+
- [Use deterministic credentials in production environments](https://learn.microsoft.com/dotnet/azure/sdk/authentication/best-practices?tabs=aspdotnet#use-deterministic-credentials-in-production-environments)
57+
- [GitHub PR dotnet/aspire#11832](https://github.com/dotnet/aspire/pull/11832)
58+
- [Azure SDK resilience improvements](https://github.com/Azure/azure-sdk-for-net/pull/52545)
59+
60+
## Recommended action
61+
62+
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:
63+
64+
### Option 1: Use specific credential types explicitly
65+
66+
Don't use `DefaultAzureCredential` in your application. Instead, explicitly use `EnvironmentCredential` or `WorkloadIdentityCredential` in production code.
67+
68+
### Option 2: Remove the environment variable in your deployment
69+
70+
Implement a `PublishAsAzureContainerApp` callback and remove the environment variable from the bicep:
71+
72+
```csharp
73+
builder.AddProject<Projects.Frontend>("frontend")
74+
.PublishAsAzureContainerApp((infra, app) =>
75+
{
76+
// Remove the AZURE_TOKEN_CREDENTIALS env var to restore previous behavior
77+
var containerAppContainer = app.Template.Containers[0].Value!;
78+
var azureTokenCredentialEnv = containerAppContainer.Env
79+
.Single(v => v.Value!.Name.Value == "AZURE_TOKEN_CREDENTIALS");
80+
containerAppContainer.Env.Remove(azureTokenCredentialEnv);
81+
});
82+
```
83+
84+
For Azure App Service, use a similar approach with `PublishAsAzureAppService`:
85+
86+
```csharp
87+
builder.AddProject<Projects.Frontend>("frontend")
88+
.PublishAsAzureAppService((infra, app) =>
89+
{
90+
// Remove the AZURE_TOKEN_CREDENTIALS env var to restore previous behavior
91+
var settings = app.Properties.SiteConfig.Value!.AppSettings!;
92+
var azureTokenCredentialSetting = settings
93+
.Single(s => s.Value!.Name.Value == "AZURE_TOKEN_CREDENTIALS");
94+
settings.Remove(azureTokenCredentialSetting);
95+
});
96+
```
97+
98+
## Affected APIs
99+
100+
- <xref:Aspire.Hosting.Azure.AzureContainerAppExtensions.AddAzureContainerAppEnvironment*?displayProperty=fullName>
101+
- <xref:Aspire.Hosting.Azure.AzureAppServiceEnvironmentExtensions.AddAzureAppServiceEnvironment*?displayProperty=fullName>

‎docs/compatibility/13.0/index.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Breaking changes in Aspire 13.0
3+
titleSuffix: ""
4+
description: Navigate to the breaking changes in Aspire 13.0.
5+
ms.date: 10/17/2025
6+
---
7+
8+
# Breaking changes in Aspire 13.0
9+
10+
If you're migrating an app to Aspire 13.0, the breaking changes listed here might affect you.
11+
12+
[!INCLUDE [binary-source-behavioral](../includes/binary-source-behavioral.md)]
13+
14+
> [!NOTE]
15+
> This article is a work in progress. It's not a complete list of breaking changes in Aspire 13.0.
16+
17+
## Breaking changes
18+
19+
| Title | Type of change | Introduced version |
20+
|--|--|--|
21+
| [DefaultAzureCredential defaults to ManagedIdentityCredential on ACA and App Service](defaultazurecredential-managedidentity-default.md) | Behavioral change | 13.0 |

‎docs/compatibility/toc.yml‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,19 @@ items:
55
href: ../get-started/aspire-overview.md
66
- name: Breaking changes
77
href: breaking-changes.md
8-
- name: Aspire 9.5
8+
- name: Aspire 13.0
99
expanded: true
1010
items:
11+
- name: Overview
12+
href: 13.0/index.md
13+
- name: Breaking changes in 13.0
14+
expanded: true
15+
items:
16+
- name: DefaultAzureCredential defaults to ManagedIdentityCredential on ACA and App Service
17+
href: 13.0/defaultazurecredential-managedidentity-default.md
18+
- name: Aspire 9.5
19+
expanded: false
20+
items:
1121
- name: Overview
1222
href: 9.5/index.md
1323
- name: Breaking changes in 9.5

0 commit comments

Comments
 (0)