New auth best practices doc

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/authentication-best-practices.md

@@ -0,0 +1,45 @@
+---
+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: conceptual
+ms.date: 01/15/2025
+---
+
+# Authentication best practices with the Azure Identity library for .NET
+
+This article offers guidelines to help you maximize the performance and reliability of your .NET apps when authenticating to Azure services. To make the most of the Azure Identity library for .NET, it's important to understand potential issues and mitigation techniques.
+
+## Use deterministic credentials in production environments
+
+[!INCLUDE [default-azure-credential-usage](../includes/default-azure-credential-usage.md)]
+
+## Reuse credential instances
+
+Reuse credential instances when possible to improve app resilience and 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`:
+
+:::code language="csharp" source="../snippets/authentication/best-practices/Program.cs" id="snippet_credential_reuse_Dac" highlight="6,7" :::
+
+For information on this approach, see [Authenticate using Microsoft Entra ID](/dotnet/azure/sdk/aspnetcore-guidance?tabs=api#authenticate-using-microsoft-entra-id).
+
+Other types of .NET apps can reuse credential instances as follows:
+
+:::code language="csharp" source="../snippets/authentication/best-practices/Program.cs" id="snippet_credential_reuse_noDac" highlight="8, 12" :::
+
+## Understand the managed identity retry strategy
+
+The Azure Identity library for .NET allows you to authenticate via managed identity with `ManagedIdentityCredential`. The way you use `ManagedIdentityCredential` impacts the applied retry strategy:
+
+- When used via `DefaultAzureCredential`:
+  - No retries are attempted when the initial token acquisition attempt fails or times out after a short duration, which makes this the least resilient option.
+- 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.
+  - 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/authentication/best-practices/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)

docs/azure/sdk/authentication/credential-chains.md

@@ -108,16 +108,7 @@ The preceding code sample creates a tailored credential chain comprised of two c
 
 ## Usage guidance for DefaultAzureCredential
 
-`DefaultAzureCredential` is undoubtedly the easiest way to get started with the Azure Identity library, but with that convenience comes tradeoffs. Once you deploy your app to Azure, you should understand the app's authentication requirements. For that reason, strongly consider moving from `DefaultAzureCredential` to one of the following solutions:
-
-- A specific `TokenCredential` implementation, such as `ManagedIdentityCredential`. See the [**Derived** list](/dotnet/api/azure.core.tokencredential?view=azure-dotnet&preserve-view=true#definition) for options.
-- A pared-down `ChainedTokenCredential` implementation optimized for the Azure environment in which your app runs.
-
-Here's why:
-
-- **Debugging challenges**: When authentication fails, it can be challenging to debug and identify the offending credential. You must enable logging to see the progression from one credential to the next and the success/failure status of each. For more information, see [Debug a chained credential](#debug-a-chained-credential).
-- **Performance overhead**: The process of sequentially trying 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.
-- **Unpredictable behavior**: `DefaultAzureCredential` checks for the presence of certain [environment variables][env-vars]. It's possible that someone could add or modify these environment variables at the system level on the host machine. Those changes apply globally and therefore alter the behavior of `DefaultAzureCredential` at runtime in any app running on that machine.
+[!INCLUDE [default-azure-credential-usage](../includes/default-azure-credential-usage.md)]
 
 ## Debug a chained credential
 

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

@@ -0,0 +1,30 @@
+
+`DefaultAzureCredential` is the most approachable way to get started with the Azure Identity library, but that convenience also introduces certain tradeoffs:
+
+- **Debugging challenges**: When authentication fails, it can be difficult to identify and [debug the offending credential](/dotnet/azure/sdk/authentication/credential-chains?tabs=dac#debug-a-chained-credential). Enable logging to see the sequential progression and success or failure status of each credential.
+- **Performance overhead**: Sequential credential attempts can introduce performance overhead. For example, managed identity is unavailable on a local development machine. Consequently, `ManagedIdentityCredential` always fails locally, unless explicitly disabled via its corresponding `Exclude`-prefixed property.
+- **Unpredictable behavior**: `DefaultAzureCredential` checks for certain environment variables as part of its sequential search through a [chain](/dotnet/api/azure.identity.defaultazurecredential?view=azure-dotnet) of potential credentials. It's possible that someone could add or modify these [environment variables](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/identity/Azure.Identity/README.md#environment-variables) at the system level on the host machine. Those changes apply globally and therefore alter the behavior of `DefaultAzureCredential` at runtime in any app running on that machine. A user could also install and sign-in to tooling such as the Azure CLI on the host machine that could potentially impact with credential is selected by `DefaultAzureCredential`.
+
+In a production environment, the unpredictability of `DefaultAzureCredential` can introduce significant and sometimes subtle problems. 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. Without telling the support team, a developer installs the Azure CLI on that VM and runs the `az login` command to authenticate to Azure.
+1. Due to a separate configuration change in the Azure environment, authentication via the original managed identity unexpectedly begins to fail silently.
+1. `DefaultAzureCredential` skips the failed `ManagedIdentityCredential` and searches for the next available credential, which is the Azure CLI credentials.
+1. The application starts utilizing the Azure CLI credentials rather than the managed identity, which may fail or result in unexpected elevation or reduction of privileges.
+
+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:
+
+- A specific `TokenCredential` implementation, such as `ManagedIdentityCredential`. See the [**Derived** list](/dotnet/api/azure.core.tokencredential?view=azure-dotnet&preserve-view=true#definition) for options.
+- A pared-down `ChainedTokenCredential` implementation optimized for the Azure environment in which your app runs. `ChainedTokenCredential` essentially creates a specific allow-list of acceptable credential options, such as `ManagedIdentity` for production and `VisualStudioCredential` for development.
+
+For example, consider the following `DefaultAzureCredential` configuration:
+
+:::code language="csharp" source="../snippets/authentication/credential-chains/Program.cs" id="snippet_Dac" highlight="6,7":::
+
+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.

docs/azure/sdk/snippets/authentication/Directory.Packages.props

@@ -8,6 +8,7 @@
     <PackageVersion Include="Azure.Identity.Broker" Version="1.1.0" />
     <PackageVersion Include="Azure.Storage.Blobs" Version="12.21.2" />
     <PackageVersion Include="Microsoft.Extensions.Azure" Version="1.7.5" />
+	  <PackageVersion Include="Azure.Security.KeyVault.Secrets" Version="4.7.0" />
 
     <!-- ASP.NET Core packages -->
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="8.0.8" />

docs/azure/sdk/snippets/authentication/best-practices/AuthBestPractices.csproj

@@ -0,0 +1,16 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+	  <PackageReference Include="Azure.Security.KeyVault.Secrets" />
+	  <PackageReference Include="Azure.Storage.Blobs" />
+	  <PackageReference Include="Microsoft.Extensions.Azure"/>
+  </ItemGroup>
+
+</Project>

docs/azure/sdk/snippets/authentication/best-practices/Program.cs

@@ -0,0 +1,82 @@
+using Azure.Identity;
+using Azure.Security.KeyVault.Secrets;
+using Azure.Storage.Blobs;
+using Microsoft.Extensions.Azure;
+
+var userAssignedClientId = "<user-assigned-client-id>";
+var builder = WebApplication.CreateBuilder(args);
+
+#region snippet_credential_reuse_Dac
+builder.Services.AddAzureClients(clientBuilder =>
+{
+    clientBuilder.AddSecretClient(new Uri("<key-vault-url>"));
+    clientBuilder.AddBlobServiceClient(new Uri("<blob-storage-uri>"));
+
+    DefaultAzureCredential credential = new();
+    clientBuilder.UseCredential(credential);
+});
+#endregion snippet_credential_reuse_Dac
+
+#region snippet_credential_reuse_noDac
+ChainedTokenCredential credentialChain = new(
+    new ManagedIdentityCredential(
+        ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId)),
+    new VisualStudioCredential());
+
+BlobServiceClient blobServiceClient = new(
+    new Uri("<blob-storage-uri>"),
+    credentialChain);
+
+SecretClient secretClient = new(
+    new Uri("<key-vault-url>"),
+    credentialChain);
+#endregion snippet_credential_reuse_noDac
+
+#region snippet_retries
+ManagedIdentityCredentialOptions miCredentialOptions = new(
+        ManagedIdentityId.FromUserAssignedClientId(userAssignedClientId)
+    )
+    {
+        Retry =
+        {
+            MaxRetries = 3,
+            Delay = TimeSpan.FromSeconds(0.5),
+        }
+    };
+    ChainedTokenCredential tokenChain = new(
+        new ManagedIdentityCredential(miCredentialOptions),
+        new VisualStudioCredential()
+    );
+#endregion
+
+builder.Services.AddEndpointsApiExplorer();
+
+var app = builder.Build();
+
+app.UseHttpsRedirection();
+
+var summaries = new[]
+{
+    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
+};
+
+app.MapGet("/weatherforecast", () =>
+{
+    var forecast = Enumerable.Range(1, 5).Select(index =>
+        new WeatherForecast
+        (
+            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
+            Random.Shared.Next(-20, 55),
+            summaries[Random.Shared.Next(summaries.Length)]
+        ))
+        .ToArray();
+    return forecast;
+})
+.WithName("GetWeatherForecast");
+
+app.Run();
+
+internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
+{
+    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
+}

docs/azure/sdk/snippets/authentication/best-practices/Properties/launchSettings.json

@@ -0,0 +1,12 @@
+{
+  "profiles": {
+    "AuthBestPractices": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      },
+      "applicationUrl": "https://localhost:56902;http://localhost:56903"
+    }
+  }
+}

docs/azure/sdk/snippets/authentication/best-practices/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

docs/azure/sdk/snippets/authentication/best-practices/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}