toc

Author: alexwolfmsft

docs/azure/TOC.yml

@@ -75,6 +75,8 @@
         href: ./sdk/authentication/additional-methods.md
       - name: Credential chains
         href: ./sdk/authentication/credential-chains.md
+      - name: Azure Identity library best practices
+        href: ./sdk/authentication/authentication-best-practices.md
     - name: ASP.NET Core guidance
       href: ./sdk/aspnetcore-guidance.md
     - name: Resource management

docs/azure/sdk/authentication/best-practices.md renamed to docs/azure/sdk/authentication/authentication-best-practices.md

@@ -15,7 +15,10 @@ This article offers guidelines to help you maximize the performance and reliabil
 
 ## Reuse credential instances
 
-To improve app resilience, reuse credential instances when possible. When a credential is reused, fewer access token requests are issued to Microsoft Entra ID. Instead, an attempt is made to fetch a token from the app token cache managed by the underlying MSAL dependency. For more information, see [Token caching in the Azure Identity client library](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/samples/TokenCache.md). A high-volume app that doesn't reuse credentials may encounter HTTP 429 throttling responses from Microsoft Entra ID, which can lead to app outages.
+To improve app resilience, reuse credential instances when possible to reduce the number of access token requests issued to Microsoft Entra ID. When a credential is reused, an attempt is made to fetch a token from the app token cache managed by the underlying MSAL dependency. For more information, see [Token caching in the Azure Identity client library](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/samples/TokenCache.md). 
+
+> [!NOTE]
+> A high-volume app that doesn't reuse credentials may encounter HTTP 429 throttling responses from Microsoft Entra ID, which can lead to app outages.
 
 In an ASP.NET Core app, implement credential reuse through the `UseCredential` method of `Microsoft.Extensions.Azure`:
 
@@ -35,8 +38,8 @@ The Azure Identity library for .NET allows you to authenticate via managed ident
   - No retries are attempted when token acquisition fails.
 - When used via 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.
-  - When the Azure service to which you're authenticating provides a `Retry-After` response header, the next retry is delayed by the duration specified in that header's value.
-  - When the service doesn't provide a `Retry-After` header, the maximum permissible delay between retries is 1 minute.
+  - If the Azure service to which you're authenticating provides a `Retry-After` response header, the next retry is delayed by the duration specified in that header's value.
+  - If the service doesn't provide a `Retry-After` header, the maximum permissible delay between retries is 1 minute.
   - 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:
 
 :::code language="csharp" source="../snippets/auth-best-practices/Program.cs" id="snippet_retries" highlight="5-9":::

docs/azure/sdk/includes/default-azure-credential-usage.md

@@ -5,15 +5,15 @@ For example, consider the following hypothetical sequence of events:
 
 1. An organization's security team mandates all apps use managed identity to authenticate to Azure resources.
 1. For months, a .NET app hosted on an Azure Virtual Machine (VM) successfully uses `DefaultAzureCredential` to authenticate via managed identity.
-1. Unbeknownst to the support team, a developer installs the Azure CLI on that VM and runs the `az login` command to sign-in to Azure.
-1. Due to a change in the Azure environment, Authentication via the original managed identity unexpectedly begins to fail.
+1. Without telling the support team, a developer installs the Azure CLI on that VM and runs the `az login` command to sign-in to Azure.
+1. Due to a separate configuration change in the Azure environment, Authentication via the original managed identity unexpectedly begins to fail.
 1. `DefaultAzureCredential` skips the failed `ManagedIdentityCredential` and searches for the next available credential, which is the Azure CLI credentials.
-1. Because logging is disabled by default, nobody is aware of this failure, as `DefaultAzureCredential` recovers gracefully.
+1. Because logging is disabled by default, the team is unaware of this silent authentication failure.
 
 `DefaultAzureCredential` also introduces the following challenges in some scenarios:
 
 - **Debugging challenges**: When authentication fails, it can be difficult to debug and identify the offending credential. You must enable logging to see the progression from one credential to the next and the success or failure status of each. For more information, see [Debug a chained credential](/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#debug-a-chained-credential).
-- **Performance overhead**: Sequentially attempting multiple credentials can introduce performance overhead. For example, when running on a local development machine, managed identity is unavailable. Consequently, `ManagedIdentityCredential` always fails in the local development environment, unless explicitly disabled via its corresponding `Exclude`-prefixed property.
+- **Performance overhead**: Sequentially attempting multiple credentials can introduce performance overhead. For example, on a local development machine, managed identity is unavailable. Consequently, `ManagedIdentityCredential` always fails locally, unless explicitly disabled via its corresponding `Exclude`-prefixed property.
 
 To prevent these types of subtle issues or silent failures in production apps, strongly consider moving from `DefaultAzureCredential` to one of the following deterministic solutions:
 
@@ -27,3 +27,5 @@ For example, consider the following `DefaultAzureCredential` configuration:
 Replace the preceding code with the following `ChainedTokenCredential` implementation to intentionally specify your desired credentials:
 
 :::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_Ctc" highlight="6-8":::
+
+In this example, `ManagedIdentityCredential` would be automatically discovered in production, while `VisualStudioCredential` would work in local development environments.