From ed032dd4aaab2e1e577573a86dbbc44b3b68c146 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Wed, 17 Sep 2025 16:38:28 -0500 Subject: [PATCH 1/9] Update managed identity retry strategy section --- .../sdk/authentication/best-practices.md | 38 +++++++++++++++---- .../best-practices/CCA/Program.cs | 16 +++++++- 2 files changed, 45 insertions(+), 9 deletions(-) diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index 19c68f1d7346d..ba5e1570eae37 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -2,7 +2,7 @@ title: Authentication best practices with the Azure Identity library for .NET description: This article describes authentication best practices to follow when using the Azure Identity library for .NET. ms.topic: concept-article -ms.date: 02/14/2025 +ms.date: 09/17/2025 --- # Authentication best practices with the Azure Identity library for .NET @@ -71,13 +71,35 @@ To only call `GetToken` when necessary, observe the `RefreshOn` date and proacti ## Understand the managed identity retry strategy -The Azure Identity library for .NET allows you to authenticate via managed identity with `ManagedIdentityCredential`. The way in which you use `ManagedIdentityCredential` impacts the applied retry strategy. When used via: +The Azure Identity library for .NET allows you to authenticate via managed identity with `ManagedIdentityCredential`. The mode in which you use `ManagedIdentityCredential` impacts the applied retry strategy. -- `DefaultAzureCredential`, no retries are attempted when the initial token acquisition attempt fails or times out after a short duration. This is the least resilient option because it's optimized to "fail fast" for an efficient development inner loop. -- Any other approach, such as `ChainedTokenCredential` or `ManagedIdentityCredential` directly: - - The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted, by default. This option is optimized for resilience but introduces potentially unwanted delays in the development inner loop. - - To change any of the default retry settings, use the `Retry` property on `ManagedIdentityCredentialOptions`. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: +1. "Fail fast" mode - :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries" highlight="5-9"::: + - **When to use:** For local development scenarios where you want quick feedback + - **How to activate:** Use `DefaultAzureCredential` in one of the following ways: + - Without setting environment variable `AZURE_TOKEN_CREDENTIALS` + - With environment variable `AZURE_TOKEN_CREDENTIALS` set to a string other than `ManagedIdentityCredential` + - **How it works:** No retries are attempted when the initial token acquisition attempt fails or times out after a short duration. This is the least resilient mode because it's optimized to "fail fast" for an efficient development inner loop. -For more information on customizing retry policies, see [Setting a custom retry policy](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Configuration.md#setting-a-custom-retry-policy). +1. Resilient mode + + - **When to use:** For production scenarios where resilience is important + - **How to activate:** Take one of the following approaches: + - Use `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS` environment variable set to `ManagedIdentityCredential` + - Use `ChainedTokenCredential` containing `ManagedIdentityCredential` + - Use `ManagedIdentityCredential` directly + - **How it works:** The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted, by default. This mode is optimized for resilience but introduces potentially unwanted delays in the development inner loop. + + To change the default retry settings, use the property. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: + + # [DefaultAzureCredential](#tab/dac) + + :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries_dac" highlight="5-9"::: + + # [ManagedIdentityCredential](#tab/mic) + + :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries_mic" highlight="5-9"::: + + --- + + For more information on customizing retry policies, see [Setting a custom retry policy](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Configuration.md#setting-a-custom-retry-policy). diff --git a/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs b/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs index cc05915bcc901..f53b296a1cbd5 100644 --- a/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs +++ b/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs @@ -36,7 +36,7 @@ }); #endregion snippet_credential_reuse_AspNetCore -#region snippet_retries +#region snippet_retries_mic ManagedIdentityCredentialOptions miCredentialOptions = new( ManagedIdentityId.FromUserAssignedClientId(clientId) ) @@ -51,6 +51,20 @@ ManagedIdentityCredential miCredential = new(miCredentialOptions); #endregion +#region snippet_retries_dac +DefaultAzureCredential credential = new( + new DefaultAzureCredentialOptions + { + ManagedIdentityClientId = clientId, + Retry = + { + MaxRetries = 3, + Delay = TimeSpan.FromSeconds(0.5), + } + } +); +#endregion + builder.Services.AddEndpointsApiExplorer(); var app = builder.Build(); From 7b9f771694db70a68289f4512b0664d1437fc060 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Wed, 17 Sep 2025 16:42:10 -0500 Subject: [PATCH 2/9] Update code sample --- .../azure/sdk/authentication/best-practices.md | 2 +- .../best-practices/CCA/Program.cs | 18 +++++++++--------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index ba5e1570eae37..f4d7c91724446 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -94,7 +94,7 @@ The Azure Identity library for .NET allows you to authenticate via managed ident # [DefaultAzureCredential](#tab/dac) - :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries_dac" highlight="5-9"::: + :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries_dac" highlight="4-8"::: # [ManagedIdentityCredential](#tab/mic) diff --git a/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs b/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs index f53b296a1cbd5..5bd701f85f079 100644 --- a/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs +++ b/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs @@ -52,17 +52,17 @@ #endregion #region snippet_retries_dac -DefaultAzureCredential credential = new( - new DefaultAzureCredentialOptions +DefaultAzureCredentialOptions dacOptions = new() +{ + ManagedIdentityClientId = clientId, + Retry = { - ManagedIdentityClientId = clientId, - Retry = - { - MaxRetries = 3, - Delay = TimeSpan.FromSeconds(0.5), - } + MaxRetries = 3, + Delay = TimeSpan.FromSeconds(0.5), } -); +}; + +DefaultAzureCredential credential = new(dacOptions); #endregion builder.Services.AddEndpointsApiExplorer(); From 92522b720a237001c1c9250814de3993096c442d Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Wed, 17 Sep 2025 16:49:21 -0500 Subject: [PATCH 3/9] Update code sample --- docs/azure/sdk/authentication/best-practices.md | 10 +--------- .../authentication/best-practices/CCA/Program.cs | 16 +--------------- 2 files changed, 2 insertions(+), 24 deletions(-) diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index f4d7c91724446..00a6c21ee2a6a 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -90,16 +90,8 @@ The Azure Identity library for .NET allows you to authenticate via managed ident - Use `ManagedIdentityCredential` directly - **How it works:** The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted, by default. This mode is optimized for resilience but introduces potentially unwanted delays in the development inner loop. - To change the default retry settings, use the property. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: - - # [DefaultAzureCredential](#tab/dac) - - :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries_dac" highlight="4-8"::: - - # [ManagedIdentityCredential](#tab/mic) + To change the default retry settings, use the property on `DefaultAzureCredentialOptions` or `ManagedIdentityCredentialOptions`. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries_mic" highlight="5-9"::: - --- - For more information on customizing retry policies, see [Setting a custom retry policy](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Configuration.md#setting-a-custom-retry-policy). diff --git a/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs b/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs index 5bd701f85f079..cc05915bcc901 100644 --- a/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs +++ b/docs/azure/sdk/snippets/authentication/best-practices/CCA/Program.cs @@ -36,7 +36,7 @@ }); #endregion snippet_credential_reuse_AspNetCore -#region snippet_retries_mic +#region snippet_retries ManagedIdentityCredentialOptions miCredentialOptions = new( ManagedIdentityId.FromUserAssignedClientId(clientId) ) @@ -51,20 +51,6 @@ ManagedIdentityCredential miCredential = new(miCredentialOptions); #endregion -#region snippet_retries_dac -DefaultAzureCredentialOptions dacOptions = new() -{ - ManagedIdentityClientId = clientId, - Retry = - { - MaxRetries = 3, - Delay = TimeSpan.FromSeconds(0.5), - } -}; - -DefaultAzureCredential credential = new(dacOptions); -#endregion - builder.Services.AddEndpointsApiExplorer(); var app = builder.Build(); From 364e61045f06253109eac1ba7c889d5aa4125d12 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Wed, 17 Sep 2025 16:52:30 -0500 Subject: [PATCH 4/9] Add headings --- .../sdk/authentication/best-practices.md | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index 00a6c21ee2a6a..07e8f92b89025 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -73,25 +73,25 @@ To only call `GetToken` when necessary, observe the `RefreshOn` date and proacti The Azure Identity library for .NET allows you to authenticate via managed identity with `ManagedIdentityCredential`. The mode in which you use `ManagedIdentityCredential` impacts the applied retry strategy. -1. "Fail fast" mode +### "Fail fast" mode - - **When to use:** For local development scenarios where you want quick feedback - - **How to activate:** Use `DefaultAzureCredential` in one of the following ways: - - Without setting environment variable `AZURE_TOKEN_CREDENTIALS` - - With environment variable `AZURE_TOKEN_CREDENTIALS` set to a string other than `ManagedIdentityCredential` - - **How it works:** No retries are attempted when the initial token acquisition attempt fails or times out after a short duration. This is the least resilient mode because it's optimized to "fail fast" for an efficient development inner loop. +- **When to use:** For local development scenarios where you want quick feedback +- **How to activate:** Use `DefaultAzureCredential` in one of the following ways: + - Without setting environment variable `AZURE_TOKEN_CREDENTIALS` + - With environment variable `AZURE_TOKEN_CREDENTIALS` set to a string other than `ManagedIdentityCredential` +- **How it works:** No retries are attempted when the initial token acquisition attempt fails or times out after a short duration. This is the least resilient mode because it's optimized to "fail fast" for an efficient development inner loop. -1. Resilient mode +### Resilient mode - - **When to use:** For production scenarios where resilience is important - - **How to activate:** Take one of the following approaches: - - Use `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS` environment variable set to `ManagedIdentityCredential` - - Use `ChainedTokenCredential` containing `ManagedIdentityCredential` - - Use `ManagedIdentityCredential` directly - - **How it works:** The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted, by default. This mode is optimized for resilience but introduces potentially unwanted delays in the development inner loop. +- **When to use:** For production scenarios where resilience is important +- **How to activate:** Take one of the following approaches: + - Use `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS` environment variable set to `ManagedIdentityCredential` + - Use `ChainedTokenCredential` containing `ManagedIdentityCredential` + - Use `ManagedIdentityCredential` directly +- **How it works:** The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted, by default. This mode is optimized for resilience but introduces potentially unwanted delays in the development inner loop. - To change the default retry settings, use the property on `DefaultAzureCredentialOptions` or `ManagedIdentityCredentialOptions`. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: + To change the default retry settings, use the property on `DefaultAzureCredentialOptions` or `ManagedIdentityCredentialOptions`. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: - :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries_mic" highlight="5-9"::: + :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries_mic" highlight="5-9"::: - For more information on customizing retry policies, see [Setting a custom retry policy](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Configuration.md#setting-a-custom-retry-policy). + For more information on customizing retry policies, see [Setting a custom retry policy](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Configuration.md#setting-a-custom-retry-policy). From b219faf3dce97132a8bb871fc362c30c79762cec Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Wed, 17 Sep 2025 16:53:42 -0500 Subject: [PATCH 5/9] Update region name --- docs/azure/sdk/authentication/best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index 07e8f92b89025..9408f6df731d6 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -92,6 +92,6 @@ The Azure Identity library for .NET allows you to authenticate via managed ident To change the default retry settings, use the property on `DefaultAzureCredentialOptions` or `ManagedIdentityCredentialOptions`. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: - :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries_mic" highlight="5-9"::: + :::code language="csharp" source="../snippets/authentication/best-practices/CCA/Program.cs" id="snippet_retries" highlight="5-9"::: For more information on customizing retry policies, see [Setting a custom retry policy](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/core/Azure.Core/samples/Configuration.md#setting-a-custom-retry-policy). From e379e2d4083ff5f5336d9eb0eb19c38a8dc99500 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Thu, 18 Sep 2025 10:18:01 -0500 Subject: [PATCH 6/9] Add note --- docs/azure/sdk/authentication/best-practices.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index 9408f6df731d6..f1282f6b53814 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -85,7 +85,11 @@ The Azure Identity library for .NET allows you to authenticate via managed ident - **When to use:** For production scenarios where resilience is important - **How to activate:** Take one of the following approaches: - - Use `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS` environment variable set to `ManagedIdentityCredential` + - Use `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS` environment variable set to `ManagedIdentityCredential`. + + > [!IMPORTANT] + > This approach only operates in resilient mode when using `Azure.Identity` package version 1.16.0 or later. In earlier versions, this approach operates in "fail fast" mode. + - Use `ChainedTokenCredential` containing `ManagedIdentityCredential` - Use `ManagedIdentityCredential` directly - **How it works:** The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted, by default. This mode is optimized for resilience but introduces potentially unwanted delays in the development inner loop. From ac44040660a2f8c1f2b942eaf7b15967f36e64e1 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Thu, 18 Sep 2025 10:22:33 -0500 Subject: [PATCH 7/9] Wording tweak --- docs/azure/sdk/authentication/best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index f1282f6b53814..16fe458f05381 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -85,7 +85,7 @@ The Azure Identity library for .NET allows you to authenticate via managed ident - **When to use:** For production scenarios where resilience is important - **How to activate:** Take one of the following approaches: - - Use `DefaultAzureCredential` with `AZURE_TOKEN_CREDENTIALS` environment variable set to `ManagedIdentityCredential`. + - Use `DefaultAzureCredential` with environment variable `AZURE_TOKEN_CREDENTIALS` set to `ManagedIdentityCredential` > [!IMPORTANT] > This approach only operates in resilient mode when using `Azure.Identity` package version 1.16.0 or later. In earlier versions, this approach operates in "fail fast" mode. From 87ba9d17d0bdc5b5d3fd8f8a9b402b81dcfe99c3 Mon Sep 17 00:00:00 2001 From: Scott Addie Date: Thu, 18 Sep 2025 10:23:42 -0500 Subject: [PATCH 8/9] Add clarity --- docs/azure/sdk/authentication/best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index 16fe458f05381..229d37f866133 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -88,7 +88,7 @@ The Azure Identity library for .NET allows you to authenticate via managed ident - Use `DefaultAzureCredential` with environment variable `AZURE_TOKEN_CREDENTIALS` set to `ManagedIdentityCredential` > [!IMPORTANT] - > This approach only operates in resilient mode when using `Azure.Identity` package version 1.16.0 or later. In earlier versions, this approach operates in "fail fast" mode. + > This `DefaultAzureCredential` approach only operates in resilient mode when using `Azure.Identity` package version 1.16.0 or later. In earlier versions, this approach operates in "fail fast" mode. - Use `ChainedTokenCredential` containing `ManagedIdentityCredential` - Use `ManagedIdentityCredential` directly From 6a3c4f1b20f76c50b18828add2e2cca2fc2922f4 Mon Sep 17 00:00:00 2001 From: Scott Addie <10702007+scottaddie@users.noreply.github.com> Date: Thu, 18 Sep 2025 10:36:03 -0500 Subject: [PATCH 9/9] Update docs/azure/sdk/authentication/best-practices.md Co-authored-by: Christopher Scott --- docs/azure/sdk/authentication/best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/azure/sdk/authentication/best-practices.md b/docs/azure/sdk/authentication/best-practices.md index 229d37f866133..ddbc96675c833 100644 --- a/docs/azure/sdk/authentication/best-practices.md +++ b/docs/azure/sdk/authentication/best-practices.md @@ -92,7 +92,7 @@ The Azure Identity library for .NET allows you to authenticate via managed ident - Use `ChainedTokenCredential` containing `ManagedIdentityCredential` - Use `ManagedIdentityCredential` directly -- **How it works:** The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted, by default. This mode is optimized for resilience but introduces potentially unwanted delays in the development inner loop. +- **How it works:** The time interval between retries starts at 0.8 seconds, and a maximum of five retries are attempted with exponential backoff, by default. This mode is optimized for resilience but introduces potentially unwanted delays in the development inner loop. To change the default retry settings, use the property on `DefaultAzureCredentialOptions` or `ManagedIdentityCredentialOptions`. For example, retry a maximum of three times, with a starting interval of 0.5 seconds: