Merge pull request #216450 from yoelhor/patch-306

[AzureAD] Update MI overview and quick start

Author: Stacyrch140

articles/active-directory/managed-identities-azure-resources/how-managed-identities-work-vm.md

@@ -12,7 +12,7 @@ ms.subservice: msi
 ms.devlang:
 ms.topic: conceptual
 ms.custom: mvc
-ms.date: 02/17/2022
+ms.date: 10/30/2022
 ms.author: barclayn
 ms.collection: M365-identity-device-management
 ---
@@ -33,7 +33,9 @@ Your code can use a managed identity to request access tokens for services that
 
 The following diagram shows how managed service identities work with Azure virtual machines (VMs):
 
-![Managed service identities and Azure VMs](media/how-managed-identities-work-vm/data-flow.png)
+[![Managed service identities and Azure VMs](media/how-managed-identities-work-vm/data-flow.png)](media/how-managed-identities-work-vm/data-flow.png#lightbox)
+
+The following table shows the differences between the system-assigned and user-assigned managed identities:
 
 |  Property    | System-assigned managed identity | User-assigned managed identity |
 |------|----------------------------------|--------------------------------|
@@ -48,7 +50,7 @@ The following diagram shows how managed service identities work with Azure virtu
 
 2. Azure Resource Manager creates a service principal in Azure AD for the identity of the VM. The service principal is created in the Azure AD tenant that's trusted by the subscription.
 
-3. Azure Resource Manager updates the VM identity using the Azure Instance Metadata Service identity endpoint, providing the endpoint with the service principal client ID and certificate.
+3. Azure Resource Manager updates the VM identity using the Azure Instance Metadata Service identity endpoint (for [Windows](/azure/virtual-machines/windows/instance-metadata-service) and [Linux](/azure/virtual-machines/linux/instance-metadata-service)), providing the endpoint with the service principal client ID and certificate.
 
 4. After the VM has an identity, use the service principal information to grant the VM access to Azure resources. To call Azure Resource Manager, use Azure role-based access control (Azure RBAC) to assign the appropriate role to the VM service principal. To call Key Vault, grant your code access to the specific secret or key in Key Vault.
 

articles/active-directory/managed-identities-azure-resources/overview.md

@@ -12,7 +12,7 @@ ms.subservice: msi
 ms.devlang:
 ms.topic: overview
 ms.custom: mvc
-ms.date: 06/24/2022
+ms.date: 10/30/2022
 ms.author: barclayn
 ms.collection: M365-identity-device-management
 
@@ -42,9 +42,16 @@ Here are some of the benefits of using managed identities:
 
 There are two types of managed identities:
 
-- **System-assigned**. Some Azure services allow you to enable a managed identity directly on a service instance. When you enable a system-assigned managed identity, an identity is created in Azure AD. The identity is tied to the lifecycle of that service instance. When the resource is deleted, Azure automatically deletes the identity for you. By design, only that Azure resource can use this identity to request tokens from Azure AD.
-- **User-assigned**. You may also create a managed identity as a standalone Azure resource. You can [create a user-assigned managed identity](how-to-manage-ua-identity-portal.md) and assign it to one or more instances of an Azure service. For user-assigned managed identities, the identity is managed separately from the resources that use it. </br></br>
+- **System-assigned**. Some Azure resources, such as virtual machines allow you to enable a managed identity directly on the resource. When you enable a system-assigned managed identity: 
+    - A service principal of a special type is created in Azure AD for the identity. The service principal is tied to the lifecycle of that Azure resource. When the Azure resource is deleted, Azure automatically deletes the service principal for you. 
+    - By design, only that Azure resource can use this identity to request tokens from Azure AD.
+    - You authorize the managed identity to have access to one or more services.
 
+- **User-assigned**. You may also create a managed identity as a standalone Azure resource. You can [create a user-assigned managed identity](how-to-manage-ua-identity-portal.md) and assign it to one or more Azure Resources. When you enable a user-assigned managed identity:      
+    - A service principal of a special type is created in Azure AD for the identity. The service principal is managed separately from the resources that use it. 
+    - User-assigned identities can be used by multiple resources.
+    - You authorize the managed identity to have access to one or more services.
+     
 
 The following table shows the differences between the two types of managed identities:
 
@@ -55,17 +62,12 @@ The following table shows the differences between the two types of managed ident
 | Sharing across Azure resources | Can’t be shared. <br/> It can only be associated with a single Azure resource. | Can be shared. <br/> The same user-assigned managed identity can be associated with more than one Azure resource. |
 | Common use cases | Workloads that are contained within a single Azure resource. <br/> Workloads for which you need independent identities. <br/> For example, an application that runs on a single virtual machine. | Workloads that run on multiple resources and can share a single identity. <br/> Workloads that need pre-authorization to a secure resource, as part of a provisioning flow. <br/> Workloads where resources are recycled frequently, but permissions should stay consistent. <br/> For example, a workload where multiple virtual machines need to access the same resource. |
 
-> [!IMPORTANT]
-> Regardless of the type of identity chosen, a managed identity is a service principal of a special type that can only be used with Azure resources. When the managed identity is deleted, the corresponding service principal is automatically removed.
-
-<br/>
-
 ## How can I use managed identities for Azure resources?
 
 You can use managed identities by following the steps below: 
 
 1. Create a managed identity in Azure. You can choose between system-assigned managed identity or user-assigned managed identity. 
-2. When working with a user-assigned managed identity, assign the managed identity to the "source" Azure Resource, such as an Azure Logic App or an Azure Web App.
+    1. When using a user-assigned managed identity, you assign the managed identity to the "source" Azure Resource, such as a Virtual Machine, Azure Logic App or an Azure Web App.
 3. Authorize the managed identity to have access to the "target" service.
 4. Use the managed identity to access a resource. In this step, you can use the Azure SDK with the Azure.Identity library. Some "source" resources offer connectors that know how to use Managed identities for the connections. In that case, you use the identity as a feature of that "source" resource.
 
@@ -101,4 +103,4 @@ Operations on managed identities can be performed by using an Azure Resource Man
 * [How to use managed identities for App Service and Azure Functions](../../app-service/overview-managed-identity.md)
 * [How to use managed identities with Azure Container Instances](../../container-instances/container-instances-managed-identity.md)
 * [Implementing managed identities for Microsoft Azure Resources](https://www.pluralsight.com/courses/microsoft-azure-resources-managed-identities-implementing)
-* Use [workload identity federation for managed identities](../develop/workload-identity-federation.md) to access Azure Active Directory (Azure AD) protected resources without managing secrets
+* Use [workload identity federation for managed identities](../develop/workload-identity-federation.md) to access Azure Active Directory (Azure AD) protected resources without managing secrets

articles/active-directory/managed-identities-azure-resources/tutorial-linux-vm-access-arm.md

@@ -37,23 +37,26 @@ You learn how to:
 
 ## Grant access
 
-Using managed identities for Azure resources, your code can get access tokens to authenticate to resources that support Azure AD authentication. The Azure Resource Manager API supports Azure AD authentication. First, we need to grant this VM's identity access to a resource in Azure Resource Manager, in this case the Resource Group in which the VM is contained.  
+Using managed identities for Azure resources, your code can get access tokens to authenticate to resources that support Azure AD authentication. The Azure Resource Manager API supports Azure AD authentication. First, we need to grant this VM's identity access to a resource in Azure Resource Manager, in this case, the Resource Group in which the VM is contained.  
 
+1. Sign in to the [Azure portal](https://portal.azure.com) with your administrator account.
 1. Navigate to the tab for **Resource Groups**.
-2. Select the specific **Resource Group** you used for your virtual machine.
-3. Go to **Access control(IAM)** in the left panel.
-4. Click to **Add** a new role assignment for your VM. Choose **Role** as **Reader**.
-5. In the next dropdown, **Assign access to** the resource **Virtual Machine**.
-6. Next, ensure the proper subscription is listed in the **Subscription** dropdown. And for **Resource Group**, select **All resource groups**.
-7. Finally, in **Select** choose your Linux Virtual Machine in the dropdown and click **Save**.
+1. Select the **Resource Group** you want to grant the VM's managed identity access.
+1. In the left panel, select **Access control (IAM)**.
+1. Select **Add**, and then select **Add role assignment**.
+1. In the **Role** tab, select **Reader**. This role allows view all resources, but doesn't allow you to make any changes.
+1. In the **Members** tab, for the **Assign access to**, select **Managed identity**. Then, select **+ Select members**.
+1. Ensure the proper subscription is listed in the **Subscription** dropdown. And for **Resource Group**, select **All resource groups**.
+1. For the **Manage identity** dropdown, select **Virtual Machine**.
+1. Finally, in **Select** choose your Windows Virtual Machine in the dropdown and select **Save**.
 
     ![Alt image text](media/msi-tutorial-linux-vm-access-arm/msi-permission-linux.png)
 
 ## Get an access token using the VM's system-assigned managed identity and use it to call Resource Manager
 
-To complete these steps, you will need an SSH client. If you are using Windows, you can use the SSH client in the [Windows Subsystem for Linux](/windows/wsl/about). If you need assistance configuring your SSH client's keys, see [How to Use SSH keys with Windows on Azure](../../virtual-machines/linux/ssh-from-windows.md), or [How to create and use an SSH public and private key pair for Linux VMs in Azure](../../virtual-machines/linux/mac-create-ssh-keys.md).
+To complete these steps, you'll need an SSH client. If you're using Windows, you can use the SSH client in the [Windows Subsystem for Linux](/windows/wsl/about). If you need assistance configuring your SSH client's keys, see [How to Use SSH keys with Windows on Azure](../../virtual-machines/linux/ssh-from-windows.md), or [How to create and use an SSH public and private key pair for Linux VMs in Azure](../../virtual-machines/linux/mac-create-ssh-keys.md).
 
-1. In the portal, navigate to your Linux VM and in the **Overview**, click **Connect**.  
+1. In the portal, navigate to your Linux VM and in the **Overview**, select **Connect**.  
 2. **Connect** to the VM with the SSH client of your choice. 
 3. In the terminal window, using `curl`, make a request to the local managed identities for Azure resources endpoint to get an access token for Azure Resource Manager.  
 

articles/active-directory/managed-identities-azure-resources/tutorial-windows-vm-access-arm.md

@@ -12,7 +12,7 @@ ms.subservice: msi
 ms.topic: quickstart
 ms.tgt_pltfrm: na
 ms.workload: identity
-ms.date: 01/11/2022
+ms.date: 10/30/2022
 ms.author: barclayn
 ms.collection: M365-identity-device-management
 ---
@@ -35,19 +35,32 @@ This tutorial shows you how to access the Azure Resource Manager API using a Win
 - You also need a Windows Virtual machine that has system assigned managed identities enabled.
   - If you need to create  a virtual machine for this tutorial, you can follow the article titled [Create a virtual machine with system-assigned identity enabled](./qs-configure-portal-windows-vm.md#system-assigned-managed-identity)
 
+## Enable
+
+[!INCLUDE [msi-tut-enable](../../../includes/active-directory-msi-tut-enable.md)]
+
 ## Grant your VM access to a resource group in Resource Manager
 
-Using managed identities for Azure resources, your code can get access tokens to authenticate to resources that support Azure AD authentication and Azure Resource Manager supports Azure AD authentication.  We need to grant this VM’s system-assigned managed identity access to a resource in Resource Manager, in this case the Resource Group where you created the VM. Assign the [Reader](../../role-based-access-control/built-in-roles.md#reader) role to the managed-identity at the scope of the resource group we created for your **Windows VM**.
- 
-For detailed steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.md).
+Using managed identities for Azure resources, your application can get access tokens to authenticate to resources that support Azure AD authentication. The Azure Resource Manager API supports Azure AD authentication. We grant this VM's identity access to a resource in Azure Resource Manager, in this case a Resource Group. We assign the [Reader](../../role-based-access-control/built-in-roles.md#reader) role to the managed-identity at the scope of the resource group. 
+
+1. Sign in to the [Azure portal](https://portal.azure.com) with your administrator account.
+1. Navigate to the tab for **Resource Groups**.
+1. Select the **Resource Group** you want to grant the VM's managed identity access.
+1. In the left panel, select **Access control (IAM)**.
+1. Select **Add**, and then select **Add role assignment**.
+1. In the **Role** tab, select **Reader**. This role allows view all resources, but doesn't allow you to make any changes.
+1. In the **Members** tab, for the **Assign access to**, select **Managed identity**. Then, select **+ Select members**.
+1. Ensure the proper subscription is listed in the **Subscription** dropdown. And for **Resource Group**, select **All resource groups**.
+1. For the **Manage identity** dropdown, select **Virtual Machine**.
+1. Finally, in **Select** choose your Windows Virtual Machine in the dropdown and select **Save**.
 
 ## Get an access token using the VM's system-assigned managed identity and use it to call Azure Resource Manager 
 
-You will need to use **PowerShell** in this portion.  If you don’t have **PowerShell** installed, download it [here](/powershell/azure/). 
+You'll need to use **PowerShell** in this portion.  If you don’t have **PowerShell** installed, download it [here](/powershell/azure/). 
 
-1.	In the portal, navigate to **Virtual Machines** and go to your Windows virtual machine and in the **Overview**, click **Connect**. 
+1.	In the portal, navigate to **Virtual Machines** and go to your Windows virtual machine and in the **Overview**, select **Connect**. 
 2.	Enter in your **Username** and **Password** for which you added when you created the Windows VM. 
-3.	Now that you have created a **Remote Desktop Connection** with the virtual machine, open **PowerShell** in the remote session. 
+3.	Now that you've created a **Remote Desktop Connection** with the virtual machine, open **PowerShell** in the remote session. 
 4.	Using the Invoke-WebRequest cmdlet, make a request to the local managed identity for Azure resources endpoint to get an access token for Azure Resource Manager.
 
     ```powershell