User-assigned identity flow (#44718)

* User-assigned identity flow

---------

Co-authored-by: Scott Addie <[email protected]>

Author: alexwolfmsft

.openpublishing.redirection.azure.json

@@ -127,6 +127,10 @@
         {
             "source_path_from_root": "/docs/azure/sdk/authentication/authentication-best-practices.md",
             "redirect_url": "/dotnet/azure/sdk/authentication/best-practices"
+        },
+        {
+            "source_path_from_root": "/docs/azure/sdk/authentication/azure-hosted-apps.md",
+            "redirect_url": "/docs/azure/sdk/authentication/system-assigned-managed-identity"
         }
     ]
 }

docs/azure/TOC.yml

@@ -66,7 +66,11 @@
         - name: Auth using developer accounts
           href: ./sdk/authentication/local-development-dev-accounts.md
       - name: Auth from Azure-hosted apps
-        href: ./sdk/authentication/azure-hosted-apps.md
+        items:
+        - name: Use a system-assigned managed identity
+          href: ./sdk/authentication/system-assigned-managed-identity.md
+        - name: Use a user-assigned managed identity
+          href: ./sdk/authentication/user-assigned-managed-identity.md
       - name: Auth from on-premises apps
         href: ./sdk/authentication/on-premises-apps.md
       - name: Auth via configuration files

docs/azure/sdk/authentication/azure-hosted-apps.md renamed to docs/azure/sdk/authentication/system-assigned-managed-identity.md

@@ -1,30 +1,23 @@
 ---
-title: Authenticate Azure-hosted .NET apps to Azure resources
-description: Learn how to authenticate apps to Azure services when hosted in an Azure compute service like Azure App Service, Azure Functions, or Azure Virtual Machines.
+title: Authenticate Azure-hosted .NET apps to Azure resources using a system-assigned managed identity
+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
 ---
 
-# Authenticate Azure-hosted apps to Azure resources with the Azure SDK for .NET
+# Authenticate Azure-hosted .NET apps to Azure resources using a system-assigned managed identity
 
 The recommended approach to authenticate an Azure-hosted app to other Azure resources is to use a [managed identity](/entra/identity/managed-identities-azure-resources/overview). This approach is [supported for most Azure services](/entra/identity/managed-identities-azure-resources/managed-identities-status), including apps hosted on Azure App Service, Azure Container Apps, and Azure Virtual Machines. Discover more about different authentication techniques and approaches on the [authentication overview](/dotnet/azure/sdk/authentication) page. In the sections ahead, you'll learn:
 
 - Essential managed identity concepts
-- How to create a managed identity for your app
-- How to assign roles to the managed identity
-- How to authenticate using the managed identity from your app code
+- How to create a system-assigned managed identity for your app
+- How to assign roles to the system-assigned managed identity
+- How to authenticate using the system-assigned managed identity from your app code
 
-## Essential managed identity concepts
+[!INCLUDE [managed-identity-concepts](../includes/managed-identity-concepts.md)]
 
-A managed identity enables your app to securely connect to other Azure resources without the use of secret keys or other application secrets. Internally, Azure tracks the identity and which resources it's allowed to connect to. Azure uses this information to automatically obtain Microsoft Entra tokens for the app to allow it to connect to other Azure resources.
-
-There are two types of managed identities to consider when configuring your hosted app:
-
-- **System-assigned** identities are enabled directly on an Azure resource and are tied to its life cycle. When the resource is deleted, Azure automatically deletes the identity for you. System-assigned identities provide a minimalistic approach to using managed identities.
-- **User-assigned** identities are created as standalone Azure resources and offer greater flexibility and capabilities. They are ideal for solutions involving multiple Azure resources that need to share the same identity and permissions. For example, if multiple virtual machines need to access the same set of Azure resources, a user-assigned managed identity provides reusability and optimized management.
-
-The sections ahead describe the steps to enable and use a system-assigned managed identity for an Azure-hosted app. If you need to use a user-assigned managed identity, visit the [Manage user-assigned managed identities](/entra/identity/managed-identities-azure-resources/how-manage-user-assigned-managed-identities?pivots=identity-mi-methods-azp) article for more information.
+The sections ahead describe the steps to enable and use a system-assigned managed identity for an Azure-hosted app. If you need to use a user-assigned managed identity, visit the [user-assigned managed identities](/dotnet/azure/sdk/authentication/user-assigned-managed-identity) article for more information.
 
 ## Enable a system-assigned managed identity on the Azure hosting resource
 

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

@@ -0,0 +1,201 @@
+---
+title: Authenticate Azure-hosted .NET apps to Azure resources using a user-assigned managed identity
+description: Learn how to authenticate Azure-hosted .NET apps to other Azure services using a user-assigned managed identity.
+ms.topic: how-to
+ms.custom: devx-track-dotnet, engagement-fy23, devx-track-azurecli
+ms.date: 02/06/2025
+---
+
+# Authenticate Azure-hosted .NET apps to Azure resources using a user-assigned managed identity
+
+The recommended approach to authenticate an Azure-hosted app to other Azure resources is to use a [managed identity](/entra/identity/managed-identities-azure-resources/overview). This approach is [supported for most Azure services](/entra/identity/managed-identities-azure-resources/managed-identities-status), including apps hosted on Azure App Service, Azure Container Apps, and Azure Virtual Machines. Discover more about different authentication techniques and approaches on the [authentication overview](/dotnet/azure/sdk/authentication) page. In the sections ahead, you'll learn:
+
+- Essential managed identity concepts
+- How to create a user-assigned managed identity for your app
+- How to assign roles to the user-assigned managed identity
+- How to authenticate using the user-assigned managed identity from your app code
+
+[!INCLUDE [managed-identity-concepts](../includes/managed-identity-concepts.md)]
+
+The sections ahead describe the steps to enable and use a user-assigned managed identity for an Azure-hosted app. If you need to use a user-assigned managed identity, visit the [system-assigned managed identities](/dotnet/azure/sdk/authentication/system-assigned-managed-identity) article for more information.
+
+## Create a user-assigned managed identity
+
+User-assigned managed identities are created as standalone resources in your Azure subscription using the Azure portal or the Azure CLI. Azure CLI commands can be run in the [Azure Cloud Shell](https://shell.azure.com) or on a workstation with the [Azure CLI installed](/cli/azure/install-azure-cli).
+
+### [Azure portal](#tab/azure-portal)
+
+1. In the Azure portal, enter *Managed identities* in the main search bar and select the matching result under the **Services** section.
+1. On the **Managed Identities** page, select **+ Create**.
+
+    :::image type="content" source="../media/user-assigned-identity-create.png" alt-text="A screenshot showing the page to manage user-assigned identities.":::
+
+1. On the **Create User Assigned Managed Identity** page, select a subscription, resource group, and region for the user-assigned managed identity, and then provide a name.
+1. Select **Review + create** to review and validate your inputs.
+
+    :::image type="content" source="../media/user-assigned-identity-form.png" alt-text="A screenshot showing the form to create a user-assigned managed identity.":::
+
+1. Select **Create** to create the user-assigned managed identity.
+1. After the identity is created, select **Go to resource**.
+1. On the new identity's **Overview** page, copy the **Client ID** value to use for later when you configure the application code.
+
+### [Azure CLI](#tab/azure-cli)
+
+Use the Azure CLI command [`az identity create`](/cli/azure/identity?view=azure-cli-latest#az-identity-create) to create a managed identity:
+
+```azurecli
+az identity create \
+    --resource-group <resource-group-name> \
+    --name <identity-name> \
+    --query 'clientId' \
+    --output json
+```
+
+The command output prints the client ID of the created user-assigned managed identity. The client ID is used to configure application code that relies on the identity.
+
+You can always view the managed identity properties again using the [`az identity show`](/cli/azure/identity?view=azure-cli-latest#az-identity-show) command:
+
+```azurecli
+az identity show \
+    --resource-group <your-resource-group> \
+    --name <your-managed-identity-name> \
+    --output json
+```
+
+---
+
+## Assign the managed identity to your app
+
+A user-assigned managed identity can be associated with one or more Azure resources. All of the resources that use that identity gain the permissions applied through the identity's roles.
+
+### [Azure portal](#tab/azure-portal)
+
+1. In the Azure portal, navigate to the resource that hosts your app code, such as an Azure App Service or Azure Container App instance.
+1. From the resource's **Overview** page, expand **Settings** and select **Identity** from the navigation.
+1. On the **Identity** page, switch to the **User assigned** tab.
+1. Select **+ Add** to open the **Add user assigned managed identity** panel.
+1. On the **Add user assigned managed identity** panel, use the **Subscription** dropdown to filter the search results for your identities. Use the **User assigned managed identities** search box to locate the user-assigned managed identity you enabled for the Azure resource hosting your app.
+1. Select the identity and choose **Add** at the bottom of the panel to continue.
+
+    :::image type="content" source="../media/add-user-assigned-identity-to-app.png" alt-text="A screenshot showing how to associate a user-assigned identity with an app.":::
+
+### [Azure CLI](#tab/azure-cli)
+
+The Azure CLI provides different commands to assign a user-assigned managed identity to different types of hosting services.
+
+To assign a user-assigned managed identity to a resource such as an Azure App Service web app using the Azure CLI, you'll need the resource ID of the identity. Use the [`az identity show`](/cli/azure/identity?view=azure-cli-latest#az-identity-show) command to retrieve the resource ID:
+
+```azurecli
+az identity show \
+    --resource-group <your-resource-group> \
+    --name <your-managed-identity-name> \
+    --output json \
+    --query id
+```
+
+Once you have the resource ID, use the Azure CLI command `az <resourceType> identity assign` command to associate the user-assigned managed identity with different resources, such as the following:
+
+For Azure App Service, use the Azure CLI command [`az webapp identity assign`](/cli/azure/webapp/identity?view=azure-cli-latest#az-webapp-identity-assign):
+
+```azurecli
+az webapp identity assign \
+    --resource-group <resource-group-name> \
+    --name <webapp-name> \
+    --identities <user-assigned-identity-resource-id>
+```
+
+For Azure Container Apps, use the Azure CLI command [`az containerapp identity assign`](/cli/azure/containerapp/identity?view=azure-cli-latest#az-containerapp-identity-assign):
+
+```azurecli
+az containerapp identity assign \
+    --resource-group <resource-group-name> \
+    --name <containerapp-name> \
+    --identities <user-assigned-identity-resource-id>
+```
+
+For Azure Virtual Machines, use the Azure CLI command [`az vm identity assign`](/cli/azure/vm/identity?view=azure-cli-latest#az-vm-identity-assign):
+
+```azurecli
+az vm identity assign \
+    --resource-group <resource-group-name> \
+    --name <vm-name> \
+    --identities <user-assigned-identity-resource-id>
+```
+
+---
+
+## Assign roles to the managed identity
+
+Next, determine which roles your app needs and assign those roles to the managed identity. You can assign roles to a managed identity at the following scopes:
+
+- **Resource**: The assigned roles only apply to that specific resource.
+- **Resource group**: The assigned roles apply to all resources contained in the resource group.
+- **Subscription**: The assigned roles apply to all resources contained in the subscription.
+
+The following example shows how to assign roles at the resource group scope, since many apps manage all their related Azure resources using a single resource group.
+
+### [Azure portal](#tab/azure-portal)
+
+1. Navigate to the **Overview** page of the resource group that contains the app with the user-assigned managed identity.
+1. Select **Access control (IAM)** on the left navigation.
+1. On the **Access control (IAM)** page, select **+ Add** on the top menu and then choose **Add role assignment** to navigate to the **Add role assignment** page.
+
+    :::image type="content" source="../media/add-role-assignment.png" alt-text="A screenshot showing how to access the identity role assignment page.":::
+
+1. The **Add role assignment** page presents a tabbed, multi-step workflow to assign roles to identities. On the initial **Role** tab, use the search box at the top to locate the role you want to assign to the identity.
+1. Select the role from the results and then choose **Next** to move to the **Members** tab.
+1. For the **Assign access to** option, select **Managed identity**.
+1. For the **Members** option, choose **+ Select members** to open the **Select managed identities** panel.
+1. On the **Select managed identities** panel, use the **Subscription** and **Managed identity** dropdowns to filter the search results for your identities. Use the **Select** search box to locate the user-assigned managed identity you enabled for the Azure resource hosting your app.
+
+    :::image type="content" source="../media/user-assigned-identity-assign-roles.png" alt-text="A screenshot showing the managed identity assignment process.":::
+
+1. Select the identity and choose **Select** at the bottom of the panel to continue.
+1. Select **Review + assign** at the bottom of the page.
+1. On the final **Review + assign** tab, select **Review + assign** to complete the workflow.
+
+### [Azure CLI](#tab/azure-cli)
+
+To assign a role to a user-assigned managed identity using the Azure CLI, you'll need the principal ID of the identity. Use the `az identity show` command to retrieve the resource ID:
+
+```azurecli
+az identity show \
+    --resource-group <your-resource-group> \
+    --name <your-managed-identity-name> \
+    --output json \
+    --query principalId
+```
+
+Assign a role to a managed identity using the [az role assignment create](/cli/azure/role/assignment#az-role-assignment-create) command:
+
+```azurecli
+az role assignment create \
+    --assignee <your-principal-id> \
+    --role <role-name> \
+    --scope <scope>
+```
+
+To explore which roles a managed identity can be assigned, use the [az role definition list](/cli/azure/role/definition#az-role-definition-list) command:
+
+```azurecli
+az role definition list \
+    --query "sort_by([].{roleName:roleName, description:description}, &roleName)" \
+    --output table
+```
+
+For example, to allow the managed identity with the ID of `99999999-9999-9999-9999-999999999999` read, write, and delete access to Azure Storage blob containers and data to all storage accounts in the *msdocs-dotnet-sdk-auth-example* resource group, assign the application service principal to the *Storage Blob Data Contributor* role using the following command:
+
+```azurecli
+az role assignment create \
+    --assignee 99999999-9999-9999-9999-999999999999 \
+    --role "Storage Blob Data Contributor" \
+    --scope "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/msdocs-dotnet-sdk-auth-example"
+```
+
+For information on assigning permissions at the resource or subscription level using the Azure CLI, see the article [Assign Azure roles using the Azure CLI](/azure/role-based-access-control/role-assignments-cli).
+
+---
+
+## Implement DefaultAzureCredential in your application
+
+[!INCLUDE [Implement DefaultAzureCredential](<../includes/implement-user-assigned-identity.md>)]

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

@@ -0,0 +1,69 @@
+---
+ms.topic: include
+ms.date: 08/15/2024
+---
+[DefaultAzureCredential](../authentication/credential-chains.md#defaultazurecredential-overview) is an opinionated, ordered sequence of mechanisms for authenticating to Microsoft Entra ID. Each authentication mechanism is a class derived from the [TokenCredential](/dotnet/api/azure.core.tokencredential?view=azure-dotnet&preserve-view=true) class and is known as a *credential*. At runtime, `DefaultAzureCredential` attempts to authenticate using the first credential. If that credential fails to acquire an access token, the next credential in the sequence is attempted, and so on, until an access token is successfully obtained. In this way, your app can use different credentials in different environments without writing environment-specific code.
+
+To use `DefaultAzureCredential`, add the [Azure.Identity](/dotnet/api/azure.identity) and optionally the [Microsoft.Extensions.Azure](/dotnet/api/microsoft.extensions.azure) packages to your application:
+
+### [Command Line](#tab/command-line)
+
+In a terminal of your choice, navigate to the application project directory and run the following commands:
+
+```dotnetcli
+dotnet add package Azure.Identity
+dotnet add package Microsoft.Extensions.Azure
+```
+
+### [NuGet Package Manager](#tab/nuget-package)
+
+Right-click your project in Visual Studio's **Solution Explorer** window and select **Manage NuGet Packages**. Search for **Azure.Identity**, and install the matching package. Repeat this process for the **Microsoft.Extensions.Azure** package.
+
+:::image type="content" source="../media/nuget-azure-identity.png" alt-text="Install a package using the package manager.":::
+
+---
+
+Azure services are accessed using specialized client classes from the various Azure SDK client libraries. These classes and your own custom services should be registered so they can be accessed via dependency injection throughout your app. In `Program.cs`, complete the following steps to register a client class and `DefaultAzureCredential`:
+
+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 instance of `DefaultAzureCredential` to the `UseCredential` method.
+
+> [!NOTE]
+> For a user-assigned managed identity, make sure to assign the identity's `clientId` value to the `ManagedIdentityClientId` property on the `DefaultAzureCredentialOptions` object. This enables your code to discover the correct identity to use for authentication while running in azure.
+
+For example:
+
+```c#
+using Microsoft.Extensions.Azure;
+using Azure.Identity;
+
+builder.Services.AddAzureClients(clientBuilder =>
+{
+    clientBuilder.AddBlobServiceClient(
+        new Uri("https://<account-name>.blob.core.windows.net"));
+    clientBuilder.UseCredential(new DefaultAzureCredential(
+        new DefaultAzureCredentialOptions()
+        {
+            ManagedIdentityClientId = "<your-client-id>"
+        }));
+});
+```
+
+An alternative to `UseCredential` is to instantiate `DefaultAzureCredential` directly:
+
+```c#
+using Azure.Identity;
+
+builder.Services.AddSingleton<BlobServiceClient>(_ =>
+    new BlobServiceClient(
+        new Uri("https://<account-name>.blob.core.windows.net"),
+        new DefaultAzureCredential(new DefaultAzureCredentialOptions()
+        {
+            ManagedIdentityClientId = "<your-client-id>"
+        })));
+```
+
+When the preceding code runs 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. Either approach can be used to authenticate the app to Azure resources during local development.
+
+When deployed to Azure, this same code can also authenticate your app to other Azure resources. `DefaultAzureCredential` can retrieve environment settings and managed identity configurations to authenticate to other services automatically.