Update managed identity docs with latest best practices (#49696)

* Update managed identity docs with latest best practices

* React to feedback

Author: scottaddie

docs/azure/sdk/authentication/system-assigned-managed-identity.md

@@ -3,7 +3,7 @@ title: Authenticate Azure-hosted .NET apps to Azure resources using a system-ass
 description: Learn how to authenticate Azure-hosted .NET apps to other Azure services using a system-assigned managed identity.
 ms.topic: how-to
 ms.custom: devx-track-dotnet, engagement-fy23, devx-track-azurecli
-ms.date: 02/06/2025
+ms.date: 11/10/2025
 ---
 
 # Authenticate Azure-hosted .NET apps to Azure resources using a system-assigned managed identity

docs/azure/sdk/includes/implement-system-assigned-identity.md

@@ -1,6 +1,6 @@
 ---
 ms.topic: include
-ms.date: 02/12/2025
+ms.date: 11/10/2025
 ---
 
 [!INCLUDE [implement-managed-identity-concepts](implement-managed-identity-concepts.md)]
@@ -30,19 +30,10 @@ Azure services are accessed using specialized client classes from the various Az
 
 1. Include the `Azure.Identity` and `Microsoft.Extensions.Azure` namespaces via `using` directives.
 1. Register the Azure service client using the corresponding `Add`-prefixed extension method.
-1. Pass an appropriate `TokenCredential` instance to the `UseCredential` method:
-    - Use `DefaultAzureCredential` when your app is running locally.
-    - Use `ManagedIdentityCredential` when your app is running in Azure.
+1. Use an appropriate `TokenCredential` instance for the environment in which your app is running. When your app is running:
+    - In Azure, pass an instance of `ManagedIdentityCredential` to the `UseCredential` method. `ManagedIdentityCredential` discovers your managed identity configurations to authenticate to other services automatically.
+    - On your local development machine, an instance of `DefaultAzureCredential` is created on your behalf. Call `UseCredential` only if you want to [customize `DefaultAzureCredential`](../authentication/credential-chains.md#how-to-customize-defaultazurecredential) or use a different credential. `DefaultAzureCredential` looks in the environment variables for an application service principal or at locally installed developer tools, such as Visual Studio, for a set of developer credentials.
 
 :::code language="csharp" source="../snippets/authentication/system-assigned-managed-identity/Program.cs" id="snippet_MIC_UseCredential":::
 
-An alternative to the `UseCredential` method is to provide the credential to the service client directly:
-
-:::code language="csharp" source="../snippets/authentication/system-assigned-managed-identity/Program.cs" id="snippet_MIC":::
-
 ---
-
-The preceding code behaves differently depending on the environment where it's running:
-
-- On your local development workstation, `DefaultAzureCredential` looks in the environment variables for an application service principal or at locally installed developer tools, such as Visual Studio, for a set of developer credentials.
-- When deployed to Azure, `ManagedIdentityCredential` discovers your managed identity configurations to authenticate to other services automatically.

docs/azure/sdk/includes/implement-user-assigned-identity.md

@@ -1,6 +1,6 @@
 ---
 ms.topic: include
-ms.date: 02/12/2025
+ms.date: 11/10/2025
 ---
 
 [!INCLUDE [implement-managed-identity-concepts](implement-managed-identity-concepts.md)]
@@ -30,9 +30,9 @@ Azure services are accessed using specialized client classes from the various Az
 
 1. Include the `Azure.Identity` and `Microsoft.Extensions.Azure` namespaces via `using` directives.
 1. Register the Azure service client using the corresponding `Add`-prefixed extension method.
-1. Pass an appropriate `TokenCredential` instance to the `UseCredential` method:
-    - Use `DefaultAzureCredential` when your app is running locally
-    - Use `ManagedIdentityCredential` when your app is running in Azure and configure either the client ID, resource ID, or object ID.
+1. Use an appropriate `TokenCredential` instance for the environment in which your app is running. When your app is running:
+    - In Azure, pass an instance of `ManagedIdentityCredential` to the `UseCredential` method and configure either the client ID, resource ID, or object ID. `ManagedIdentityCredential` discovers your managed identity configurations to authenticate to other services automatically.
+    - On your local development machine, an instance of `DefaultAzureCredential` is created on your behalf. Call `UseCredential` only if you want to [customize `DefaultAzureCredential`](../authentication/credential-chains.md#how-to-customize-defaultazurecredential) or use a different credential. `DefaultAzureCredential` looks in the environment variables for an application service principal or at locally installed developer tools, such as Visual Studio, for a set of developer credentials.
 
 ## [Client ID](#tab/client-id)
 
@@ -51,10 +51,6 @@ The client ID is used to identify a managed identity when configuring applicatio
 
     :::code language="csharp" source="../snippets/authentication/user-assigned-managed-identity/Program.cs" id="snippet_MIC_ClientId_UseCredential":::
 
-    An alternative to the `UseCredential` method is to provide the credential to the service client directly:
-
-    :::code language="csharp" source="../snippets/authentication/user-assigned-managed-identity/Program.cs" id="snippet_MIC_ClientId":::
-
 ## [Resource ID](#tab/resource-id)
 
 The resource ID uniquely identifies the managed identity resource within your Azure subscription using the following structure:
@@ -76,10 +72,6 @@ Resource IDs can be built by convention, which makes them more convenient when w
 
     :::code language="csharp" source="../snippets/authentication/user-assigned-managed-identity/Program.cs" id="snippet_MIC_ResourceId_UseCredential":::
 
-    An alternative to the `UseCredential` method is to provide the credential to the service client directly:
-
-    :::code language="csharp" source="../snippets/authentication/user-assigned-managed-identity/Program.cs" id="snippet_MIC_ResourceId":::
-
 ## [Object ID](#tab/object-id)
 
 A principal ID is another name for an object ID.
@@ -97,13 +89,4 @@ A principal ID is another name for an object ID.
 
     :::code language="csharp" source="../snippets/authentication/user-assigned-managed-identity/Program.cs" id="snippet_MIC_ObjectId_UseCredential":::
 
-    An alternative to the `UseCredential` method is to provide the credential to the service client directly:
-
-    :::code language="csharp" source="../snippets/authentication/user-assigned-managed-identity/Program.cs" id="snippet_MIC_ObjectId":::
-
 ---
-
-The preceding code behaves differently depending on the environment where it's running:
-
-- On your local development workstation, `DefaultAzureCredential` looks in the environment variables for an application service principal or at locally installed developer tools, such as Visual Studio, for a set of developer credentials.
-- When deployed to Azure, `ManagedIdentityCredential` discovers your managed identity configurations to authenticate to other services automatically.

docs/azure/sdk/snippets/authentication/system-assigned-managed-identity/Program.cs

@@ -1,7 +1,5 @@
 using Azure.Identity;
 using Microsoft.Extensions.Azure;
-using Azure.Storage.Blobs;
-using Azure.Core;
 
 var builder = WebApplication.CreateBuilder(args);
 
@@ -11,42 +9,15 @@
     clientBuilder.AddBlobServiceClient(
         new Uri("https://<account-name>.blob.core.windows.net"));
 
-    TokenCredential credential = null;
-
-    if (builder.Environment.IsProduction())
+    if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
     {
         // Managed identity token credential discovered when running in Azure environments
-        credential = new ManagedIdentityCredential();
-    }
-    else
-    {
-        // Running locally on dev machine - DO NOT use in production or outside of local dev
-        credential = new DefaultAzureCredential();
+        ManagedIdentityCredential credential = new(ManagedIdentityId.SystemAssigned);
+        clientBuilder.UseCredential(credential);
     }
-
-    clientBuilder.UseCredential(credential);
 });
 #endregion snippet_MIC_UseCredential
 
-#region snippet_MIC
-TokenCredential credential = null;
-
-if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
-{
-    // Managed identity token credential discovered when running in Azure environments
-    credential = new ManagedIdentityCredential();
-}
-else
-{
-    // Running locally on dev machine - DO NOT use in production or outside of local dev
-    credential = new DefaultAzureCredential();
-}
-
-builder.Services.AddSingleton<BlobServiceClient>(_ =>
-    new BlobServiceClient(
-        new Uri("https://<account-name>.blob.core.windows.net"), credential));
-#endregion snippet_MIC
-
 var app = builder.Build();
 
 if (app.Environment.IsDevelopment())
@@ -82,4 +53,4 @@
 internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
 {
     public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
-}
+}

docs/azure/sdk/snippets/authentication/user-assigned-managed-identity/Program.cs

@@ -1,6 +1,5 @@
 using Azure.Identity;
 using Microsoft.Extensions.Azure;
-using Azure.Storage.Blobs;
 using Azure.Core;
 
 var builder = WebApplication.CreateBuilder(args);
@@ -50,43 +49,15 @@ void registerUsingClientId(WebApplicationBuilder builder)
         clientBuilder.AddBlobServiceClient(
             new Uri("https://<account-name>.blob.core.windows.net"));
 
-        TokenCredential credential = null;
-
         if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
         {
             // Managed identity token credential discovered when running in Azure environments
-            credential = new ManagedIdentityCredential(
+            ManagedIdentityCredential credential = new(
                 ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
+            clientBuilder.UseCredential(credential);
         } 
-        else 
-        {
-            // Running locally on dev machine - DO NOT use in production or outside of local dev
-            credential = new DefaultAzureCredential();
-        }
-
-        clientBuilder.UseCredential(credential);
     });
     #endregion snippet_MIC_ClientId_UseCredential
-
-    #region snippet_MIC_ClientId
-    TokenCredential credential = null;
-
-    if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
-    {
-        // Managed identity token credential discovered when running in Azure environments
-        credential = new ManagedIdentityCredential(
-            ManagedIdentityId.FromUserAssignedClientId("<client-id>"));
-    }
-    else
-    {
-        // Running locally on dev machine - DO NOT use in production or outside of local dev
-        credential = new DefaultAzureCredential();
-    }
-
-    builder.Services.AddSingleton<BlobServiceClient>(_ =>
-        new BlobServiceClient(
-            new Uri("https://<account-name>.blob.core.windows.net"), credential));
-    #endregion snippet_MIC_ClientId
 }
 
 void registerUsingObjectId(WebApplicationBuilder builder)
@@ -97,43 +68,15 @@ void registerUsingObjectId(WebApplicationBuilder builder)
         clientBuilder.AddBlobServiceClient(
             new Uri("https://<account-name>.blob.core.windows.net"));
 
-        TokenCredential credential = null;
-
         if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
         {
             // Managed identity token credential discovered when running in Azure environments
-            credential = new ManagedIdentityCredential(
+            ManagedIdentityCredential credential = new(
                 ManagedIdentityId.FromUserAssignedObjectId("<object-id>"));
+            clientBuilder.UseCredential(credential);
         }
-        else
-        {
-            // Running locally on dev machine - DO NOT use in production or outside of local dev
-            credential = new DefaultAzureCredential();
-        }
-
-        clientBuilder.UseCredential(credential);
     });
     #endregion snippet_MIC_ObjectId_UseCredential
-
-    #region snippet_MIC_ObjectId
-    TokenCredential credential = null;
-
-    if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
-    {
-        // Managed identity token credential discovered when running in Azure environments
-        credential = new ManagedIdentityCredential(
-            ManagedIdentityId.FromUserAssignedObjectId("<object-id>"));
-    }
-    else
-    {
-        // Running locally on dev machine - DO NOT use in production or outside of local dev
-        credential = new DefaultAzureCredential();
-    }
-
-    builder.Services.AddSingleton<BlobServiceClient>(_ =>
-        new BlobServiceClient(
-            new Uri("https://<account-name>.blob.core.windows.net"), credential));
-    #endregion snippet_MIC_ObjectId
 }
 
 
@@ -145,46 +88,18 @@ void registerUsingResourceId(WebApplicationBuilder builder)
         clientBuilder.AddBlobServiceClient(
             new Uri("https://<account-name>.blob.core.windows.net"));
 
-        TokenCredential credential = null;
-
         if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
         {
             // Managed identity token credential discovered when running in Azure environments
-            credential = new ManagedIdentityCredential(
+            ManagedIdentityCredential credential = new(
                 ManagedIdentityId.FromUserAssignedResourceId(new ResourceIdentifier("<resource-id>")));
+            clientBuilder.UseCredential(credential);
         }
-        else
-        {
-            // Running locally on dev machine - DO NOT use in production or outside of local dev
-            credential = new DefaultAzureCredential();
-        }
-
-        clientBuilder.UseCredential(credential);
     });
     #endregion snippet_MIC_ResourceId_UseCredential
-
-    #region snippet_MIC_ResourceId
-    TokenCredential credential = null;
-
-    if (builder.Environment.IsProduction() || builder.Environment.IsStaging())
-    {
-        // Managed identity token credential discovered when running in Azure environments
-        credential = new ManagedIdentityCredential(
-            ManagedIdentityId.FromUserAssignedResourceId(new ResourceIdentifier("<resource-id>")));
-    }
-    else
-    {
-        // Running locally on dev machine - DO NOT use in production or outside of local dev
-        credential = new DefaultAzureCredential();
-    }
-
-    builder.Services.AddSingleton<BlobServiceClient>(_ =>
-        new BlobServiceClient(
-            new Uri("https://<account-name>.blob.core.windows.net"), credential));
-    #endregion snippet_MIC_ResourceId
 }
 
 internal record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
 {
     public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
-}
+}