Merge pull request #232441 from alexwolfmsft/migration-guide-user-identity

Update migration doc to user-assigned identites

Author: v-stsavell

articles/storage/common/media/create-managed-identity-portal-small.png

@@ -19,23 +19,23 @@ Application requests to Azure Storage must be authenticated using either account
 
 ## Security risks associated with Shared Key authorization
 
-The following code example demonstrates how to connect to Azure Storage using a storage account key. When you create a storage account, Azure generates access keys for that account. Many developers gravitate towards this solution because it feels familiar to options they have worked with in the past. For example, connection strings for storage accounts also use access keys as part of the string. If your application currently uses access keys, consider migrating to passwordless connections using the steps described later in this document.
+The following code example demonstrates how to connect to Azure Storage using a storage account key. When you create a storage account, Azure generates access keys for that account. Many developers gravitate towards this solution because it feels familiar to options they've worked with in the past. For example, connection strings for storage accounts also use access keys as part of the string. If your application currently uses access keys, consider migrating to passwordless connections using the steps described later in this document.
 
 ```csharp
 var blobServiceClient = new BlobServiceClient(
     new Uri("https://<storage-account-name>.blob.core.windows.net"),
     new StorageSharedKeyCredential("<storage-account-name>", "<your-access-key>"));
 ```
 
-Storage account keys should be used with caution. Developers must be diligent to never expose the keys in an unsecure location. Anyone who gains access to the key is able to authenticate. For example, if an account key is accidentally checked into source control, sent through an unsecure email, pasted into the wrong chat, or viewed by someone who shouldn't have permission, there's risk of a malicious user accessing the application. Instead, consider updating your application to use passwordless connections.
+Storage account keys should be used with caution. Developers must be diligent to never expose the keys in an unsecure location. Anyone who gains access to the key is able to authenticate. For example, if an account key is accidentally checked into source control, sent through an unsecure email, or viewed by someone who shouldn't have permission, there's risk of a malicious user accessing the application. Instead, consider updating your application to use passwordless connections.
 
 ## Migrate to passwordless connections
 
 [!INCLUDE [migrate-to-passwordless-overview](../../../includes/passwordless/migration-guide/migrate-to-passwordless-overview.md)]
 
 ## Steps to migrate an app to use passwordless authentication
 
-The following steps explain how to migrate an existing application to use passwordless connections instead of a key-based solution. These same migration steps should apply whether you are using access keys directly, or through connection strings.
+The following steps explain how to migrate an existing application to use passwordless connections instead of a key-based solution. These same migration steps should apply whether you're using access keys directly, or through connection strings.
 
 ### Configure roles and users for local development authentication
 
@@ -47,7 +47,7 @@ For local development, make sure you're authenticated with the same Azure AD acc
 
 [!INCLUDE [default-azure-credential-sign-in](../../../includes/passwordless/default-azure-credential-sign-in.md)]
 
-Next you will need to update your code to use passwordless connections.
+Next you need to update your code to use passwordless connections.
 
 1. To use `DefaultAzureCredential` in a .NET application, add the **Azure.Identity** NuGet package to your application.
 
@@ -76,121 +76,52 @@ Next you will need to update your code to use passwordless connections.
 
 #### Run the app locally
 
-After making these code changes, run your application locally. The new configuration should pick up your local credentials, such as the Azure CLI, Visual Studio, or IntelliJ. The roles you assigned to your local dev user in Azure will allow your app to connect to the Azure service locally.
+After making these code changes, run your application locally. The new configuration should pick up your local credentials, such as the Azure CLI, Visual Studio, or IntelliJ. The roles you assigned to your local dev user in Azure allows your app to connect to the Azure service locally.
 
 ### Configure the Azure hosting environment
 
-Once your application is configured to use passwordless connections and runs locally, the same code can authenticate to Azure services after it is deployed to Azure. For example, an application deployed to an Azure App Service instance that has a managed identity enabled can connect to Azure Storage.
+Once your application is configured to use passwordless connections and runs locally, the same code can authenticate to Azure services after it's deployed to Azure. The sections that follow explain how to configure a deployed application to connect to Azure Blob Storage using a managed identity.
 
-#### Create the managed identity using the Azure portal
+#### Create the managed identity
 
-[!INCLUDE [create-managed-identity-portal](../../../includes/passwordless/migration-guide/create-managed-identity-portal.md)]
+[!INCLUDE [create-managed-identity](../../../includes/passwordless/migration-guide/create-user-assigned-managed-identity.md)]
 
-Alternatively, you can also enable managed identity on an Azure hosting environment using the Azure CLI.
+#### Associate the managed identity with your web app
 
-### [Service Connector](#tab/service-connector-identity)
+You need to configure your web app to use the managed identity you created. Assign the identity to your app using either the Azure portal or the Azure CLI.
 
-You can use Service Connector to create a connection between an Azure compute hosting environment and a target service using the Azure CLI. The CLI automatically handles creating a managed identity and assigns the proper role, as explained in the [portal instructions](#create-the-managed-identity-using-the-azure-portal).
+# [Azure Portal](#tab/azure-portal-associate)
 
-If you're using an Azure App Service, use the `az webapp connection` command:
+Complete the following steps in the Azure portal to associate an identity with your app. These same steps apply to the following Azure services:
 
-```azurecli
-az webapp connection create storage-blob \
-    --resource-group <resource-group-name> \
-    --name <webapp-name> \
-    --target-resource-group <target-resource-group-name> \
-    --account <target-storage-account-name> \
-    --system-identity
-```
-
-If you're using Azure Spring Apps, use `the az spring-cloud connection` command:
-
-```azurecli
-az spring-cloud connection create storage-blob \
-    --resource-group <resource-group-name> \
-    --service <service-instance-name> \
-    --app <app-name> \
-    --deployment <deployment-name> \
-    --target-resource-group <target-resource-group> \
-    --account <target-storage-account-name> \
-    --system-identity
-```
-
-If you're using Azure Container Apps, use the `az containerapp connection` command:
-
-```azurecli
-az containerapp connection create storage-blob \
-    --resource-group <resource-group-name> \
-    --name <containerapp-name> \
-    --target-resource-group <target-resource-group-name> \
-    --account <target-storage-account-name> \
-    --system-identity
-```
-
-### [Azure App Service](#tab/app-service-identity)
-
-You can assign a managed identity to an Azure App Service instance with the [az webapp identity assign](/cli/azure/webapp/identity) command.
-
-```azurecli
-az webapp identity assign \
-    --resource-group <resource-group-name> \
-    --name <webapp-name>
-```
-
-### [Azure Spring Apps](#tab/spring-apps-identity)
-
-You can assign a managed identity to an Azure Spring Apps instance with the [az spring app identity assign](/cli/azure/spring/app/identity) command.
-
-```azurecli
-az spring app identity assign \
-    --resource-group <resource-group-name> \
-    --name <app-name> \
-    --service <service-name>
-```
-
-### [Azure Container Apps](#tab/container-apps-identity)
+* Azure Spring Apps
+* Azure Container Apps
+* Azure virtual machines
+* Azure Kubernetes Service.
 
-You can assign a managed identity to an Azure Container Apps instance with the [az container app identity assign](/cli/azure/containerapp/identity) command.
+1. Navigate to the overview page of your web app.
+1. Select **Identity** from the left navigation.
+1. On the **Identity** page, switch to the **User assigned** tab.
+1. Select **+ Add** to open the **Add user assigned managed identity** flyout.
+1. Select the subscription you used previously to create the identity.
+1. Search for the **MigrationIdentity** by name and select it from the search results.
+1. Select **Add** to associate the identity with your app.
 
-```azurecli
-az containerapp identity assign \
-    --resource-group <resource-group-name> \
-    --name <app-name>
-```
-
-### [Azure virtual machines](#tab/virtual-machines-identity)
+   :::image type="content" source="../../../articles/storage/common/media/create-user-assigned-identity-small.png" alt-text="Screenshot showing how to create a user assigned identity." lightbox="../../../articles/storage/common/media/create-user-assigned-identity.png":::
 
-You can assign a managed identity to a virtual machine with the [az vm identity assign](/cli/azure/vm/identity) command.
+# [Azure CLI](#tab/azure-cli-associate)
 
-```azurecli
-az vm identity assign \
-    --resource-group <resource-group-name> \
-    --name <virtual-machine-name>
-```
+[!INCLUDE [associate-managed-identity-cli](../../../includes/passwordless/migration-guide/associate-managed-identity-cli.md)]
 
-### [Azure Kubernetes Service](#tab/aks-identity)
+# [Service Connector](#tab/service-connector-associate)
 
-You can assign a managed identity to an Azure Kubernetes Service (AKS) instance with the [az aks update](/cli/azure/aks) command.
-
-```azurecli
-az vm identity assign \
-    --resource-group <resource-group-name> \
-    --name <virtual-machine-name>
-```
+[!INCLUDE [service-connector-commands](../../../includes/passwordless/migration-guide/service-connector-commands.md)]
 
 ---
 
 #### Assign roles to the managed identity
 
-Next, you need to grant permissions to the managed identity you created to access your storage account. You can do this by assigning a role to the managed identity, just like you did with your local development user.
-
-### [Service Connector](#tab/assign-role-service-connector)
-
-If you connected your services using the Service Connector you do not need to complete this step. The necessary configurations were handled for you:
-
-* If you selected a managed identity while creating the connection, a system-assigned managed identity was created for your app and assigned the **Storage Blob Data Contributor** role on the storage account.
-
-* If you selected connection string, the connection string was added as an app environment variable.
+Next, you need to grant permissions to the managed identity you created to access your storage account. Grant permissions by assigning a role to the managed identity, just like you did with your local development user.
 
 ### [Azure portal](#tab/assign-role-azure-portal)
 
@@ -204,15 +135,15 @@ If you connected your services using the Service Connector you do not need to co
 
 1. On the **Add role assignment** screen, for the **Assign access to** option, select **Managed identity**. Then choose **+Select members**.
 
-1. In the flyout, search for the managed identity you created by entering the name of your app service. Select the system assigned identity, and then choose **Select** to close the flyout menu.
+1. In the flyout, search for the managed identity you created by name and select it from the results. Choose **Select** to close the flyout menu.
 
    :::image type="content" source="media/migration-select-identity-small.png" alt-text="Screenshot showing how to select the assigned managed identity." lightbox="media/migration-select-identity.png":::
 
 1. Select **Next** a couple times until you're able to select **Review + assign** to finish the role assignment.
 
 ### [Azure CLI](#tab/assign-role-azure-cli)
 
-To assign a role at the resource level using the Azure CLI, you first must retrieve the resource ID using the az storage account show command. You can filter the output properties using the --query parameter.
+To assign a role at the resource level using the Azure CLI, you first must retrieve the resource ID using the [az storage account](/cli/azure/storage/account) show command. You can filter the output properties using the `--query` parameter.
 
 ```azurecli
 az storage account show \
@@ -221,7 +152,7 @@ az storage account show \
     --query id
 ```
 
-Copy the output ID from the preceding command. You can then assign roles using the az role command of the Azure CLI.
+Copy the output ID from the preceding command. You can then assign roles using the [az role assignment](/cli/azure/role/assignment) command of the Azure CLI.
 
 ```azurecli
 az role assignment create \
@@ -230,11 +161,35 @@ az role assignment create \
     --scope "<your-resource-id>"
 ```
 
+### [Service Connector](#tab/assign-role-service-connector)
+
+If you connected your services using Service Connector you don't need to complete this step. The necessary role configurations were handled for you when you ran the Service Connector CLI commands.
+
 ---
 
+#### Update the application code
+
+You need to configure your application code to look for the specific managed identity you created when it is deployed to Azure. In some scenarios, explicitly setting the managed identity for the app also prevents other environment identities from accidentally being detected and used automatically.
+
+1. On the managed identity overview page, copy the client ID value to your clipboard.
+1. Update the `DefaultAzureCredential` object in the `Program.cs` file of your app to specify this managed identity client ID.
+
+    ```csharp
+    // TODO: Update the <your-storage-account-name> and <your-managed-identity-client-id> placeholders
+    var blobServiceClient = new BlobServiceClient(
+                        new Uri("https://<your-storage-account-name>.blob.core.windows.net"),
+                        new DefaultAzureCredential(
+                            new DefaultAzureCredentialOptions() 
+                            { 
+                                ManagedIdentityClientId = "<your-managed-identity-client-id>" 
+                            }));
+    ```
+
+3. Redeploy your code to Azure after making this change in order for the configuration updates to be applied.
+
 #### Test the app
 
-After making these code changes, browse to your hosted application in the browser. Your app should be able to connect to the storage account successfully. Keep in mind that it may take several minutes for the role assignments to propagate through your Azure environment. Your application is now configured to run both locally and in a production environment without the developers having to manage secrets in the application itself.
+After deploying the updated code, browse to your hosted application in the browser. Your app should be able to connect to the storage account successfully. Keep in mind that it may take several minutes for the role assignments to propagate through your Azure environment. Your application is now configured to run both locally and in a production environment without the developers having to manage secrets in the application itself.
 
 ## Next steps
 

articles/storage/common/media/create-managed-identity-portal.png

@@ -0,0 +1,61 @@
+The following steps demonstrate how to create a user-assigned managed identity for various web hosting services. The managed identity can securely connect to other Azure services using the app configurations you set up previously.
+
+### [Service Connector](#tab/service-connector)
+
+Some app hosting environments support Service Connector, which helps you connect Azure compute services to other backing services. Service Connector automatically configures network settings and connection information.
+
+The following compute services are currently supported:
+
+* Azure App Service
+* Azure Spring Cloud
+* Azure Container Apps (preview)
+
+For this migration guide, you'll use App Service. The steps are similar on Azure Spring Apps and Azure Container Apps.
+
+> [!NOTE]
+> Azure Spring Apps currently only supports Service Connector using connection strings.
+
+1. On the main overview page of your App Service, select **Service Connector** from the left navigation.
+
+1. Select **+ Create** from the top menu and the **Create connection** panel will open.  Enter the following values:
+
+   * **Service type**: Choose **Service bus**.
+   * **Subscription**: Select the subscription you would like to use.
+   * **Connection Name**: Enter a name for your connection, such as *connector_appservice_servicebus*.
+   * **Client type**: Leave the default value selected or choose the specific client you'd like to use.
+
+   Select **Next: Authentication**.
+
+1. Select **User assigned managed identity**.
+1. Select the subscription and **MigrationIdentity** user identity you configured in the previous section.
+1. Select **Next: Networking**.
+1. Leave the default values selected, and then choose **Next: Review + Create**.
+1. After Azure validates your settings, select **Create**.
+
+The Service Connector will automatically assign the managed identity an **Azure Service Bus Data Owner** role for the service bus you selected.
+
+### [Azure portal](#tab/app-service)
+
+You can assign the correct roles to your user-assigned managed identity through the storage account settings pages.
+
+1. On the overview page of your storage account, select **Access control (IAM)**.
+1. Select **+ Add** at the top of the page and then choose **Add role assignment** from the drop down menu.
+1. On the **Add role assignment** page, leave the default **Assignment type** toggled and select **Next**.
+1. On the **Role** tab, search for *Storage Blob Data Contributor* and select the matching result. Then select **Next**.
+1. On the **Members** tab, make sure the following values are set:
+    * **Selected Role**: Storage Blob Data Contributor
+    * **Assign access to**: Select **Managed identity**.
+    * **Members**: Select **+ Select members**.
+        
+        In the flyout menu, make sure the following values are set:
+
+         * **Subscription**: Select the subscription you want to use.
+         * **Managed identity**: Select **User-assigned managed identity**.
+         * **Select**: Search for the **Migration Identity** you created earlier and select it from the results below the input.
+
+         
+1. Choose **Select** to close the flyout.
+1. Select **Review and assign** at the bottom of the page.
+1. After Azure validates your inputs, select **Assign** to complete the workflow.
+
+The correct role is assigned to the user-assigned managed identity used by your app.