Configure managed identities for Azure resources on an Azure VM using PowerShell

Managed identities for Azure resources is a feature of Azure Active Directory. Each of the Azure services that support managed identities for Azure resources are subject to their own timeline. Make sure you review the availability status of managed identities for your resource and known issues before you begin.

Managed identities for Azure resources provides Azure services with an automatically managed identity in Azure Active Directory. You can use this identity to authenticate to any service that supports Azure AD authentication, without having credentials in your code.

In this article, using PowerShell, you learn how to perform the following managed identities for Azure resources operations on an Azure VM.

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.

Prerequisites

System-assigned managed identity

In this section, you will learn how to enable and disable the system-assigned managed identity using Azure PowerShell.

Enable system-assigned managed identity during creation of an Azure VM

To create an Azure VM with the system-assigned managed identity enabled,your account needs the Virtual Machine Contributor role assignment. No additional Azure AD directory role assignments are required.

  1. Refer to one of the following Azure VM Quickstarts, completing only the necessary sections ("Sign in to Azure", "Create resource group", "Create networking group", "Create the VM").

    When you get to the "Create the VM" section, make a slight modification to the New-AzVMConfig cmdlet syntax. Be sure to add a -AssignIdentity:$SystemAssigned parameter to provision the VM with the system-assigned identity enabled, for example:

    $vmConfig = New-AzVMConfig -VMName myVM -AssignIdentity:$SystemAssigned ...
    

Note

You may optionally provision the managed identities for Azure resources VM extension, but it will soon be deprecated. We recommend using the Azure Instance Metadata identity endpoint for authentication. For more information, see Migrate from the VM extension to Azure IMDS endpoint for authentication.

Enable system-assigned managed identity on an existing Azure VM

To enable system-assigned managed identity on a VM that was originally provisioned without it, your account needs the Virtual Machine Contributor role assignment. No additional Azure AD directory role assignments are required.

  1. Sign in to Azure using Connect-AzAccount. Use an account that is associated with the Azure subscription that contains the VM.

    Connect-AzAccount
    
  2. First retrieve the VM properties using the Get-AzVM cmdlet. Then to enable a system-assigned managed identity, use the -AssignIdentity switch on the Update-AzVM cmdlet:

    $vm = Get-AzVM -ResourceGroupName myResourceGroup -Name myVM
    Update-AzVM -ResourceGroupName myResourceGroup -VM $vm -AssignIdentity:$SystemAssigned
    

Note

You may optionally provision the managed identities for Azure resources VM extension, but it will soon be deprecated. We recommend using the Azure Instance Metadata identity endpoint for authentication. For more information, see Migrate from the VM extension to Azure IMDS endpoint for authentication.

Add VM system assigned identity to a group

After you have enabled system assigned identity on a VM, you can add it to a group. The following procedure adds a VM's system assigned identity to a group.

  1. Sign in to Azure using Connect-AzAccount. Use an account that is associated with the Azure subscription that contains the VM.

    Connect-AzAccount
    
  2. Retrieve and note the ObjectID (as specified in the Id field of the returned values) of the VM's service principal:

    Get-AzADServicePrincipal -displayname "myVM"
    
  3. Retrieve and note the ObjectID (as specified in the Id field of the returned values) of the group:

    Get-AzADGroup -searchstring "myGroup"
    
  4. Add the VM's service principal to the group:

    Add-AzureADGroupMember -ObjectId "<objectID of group>" -RefObjectId "<object id of VM service principal>"
    

Disable system-assigned managed identity from an Azure VM

To disable system-assigned managed identity on a VM, your account needs the Virtual Machine Contributor role assignment. No additional Azure AD directory role assignments are required.

If you have a Virtual Machine that no longer needs the system-assigned managed identity but still needs user-assigned managed identities, use the following cmdlet:

  1. Sign in to Azure using Connect-AzAccount. Use an account that is associated with the Azure subscription that contains the VM.

    Connect-AzAccount
    
  2. Retrieve the VM properties using the Get-AzVM cmdlet and set the -IdentityType parameter to UserAssigned:

    $vm = Get-AzVM -ResourceGroupName myResourceGroup -Name myVM	
    Update-AzVm -ResourceGroupName myResourceGroup -VM $vm -IdentityType "UserAssigned"
    

If you have a virtual machine that no longer needs system-assigned managed identity and it has no user-assigned managed identities, use the following commands:

$vm = Get-AzVM -ResourceGroupName myResourceGroup -Name myVM
Update-AzVm -ResourceGroupName myResourceGroup -VM $vm -IdentityType None

Note

If you have provisioned the managed identity for Azure resources VM extension (to be deprecated), you need to remove it using the Remove-AzVMExtension. For more information, see Migrate from VM extension to Azure IMDS for authentication.

User-assigned managed identity

In this section, you learn how to add and remove a user-assigned managed identity from a VM using Azure PowerShell.

Assign a user-assigned managed identity to a VM during creation

To assign a user-assigned identity to a VM, your account needs the Virtual Machine Contributor and Managed Identity Operator role assignments. No additional Azure AD directory role assignments are required.

  1. Refer to one of the following Azure VM Quickstarts, completing only the necessary sections ("Sign in to Azure", "Create resource group", "Create networking group", "Create the VM").

    When you get to the "Create the VM" section, make a slight modification to the New-AzVMConfig cmdlet syntax. Add the -IdentityType UserAssigned and -IdentityID parameters to provision the VM with a user-assigned identity. Replace <VM NAME>,<SUBSCRIPTION ID>, <RESROURCE GROUP>, and <USER ASSIGNED IDENTITY NAME> with your own values. For example:

    $vmConfig = New-AzVMConfig -VMName <VM NAME> -IdentityType UserAssigned -IdentityID "/subscriptions/<SUBSCRIPTION ID>/resourcegroups/<RESROURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>..."
    

Note

You may optionally provision the managed identities for Azure resources VM extension, but it will soon be deprecated. We recommend using the Azure Instance Metadata identity endpoint for authentication. For more information, see Migrate from the VM extension to Azure IMDS endpoint for authentication.

Assign a user-assigned managed identity to an existing Azure VM

To assign a user-assigned identity to a VM, your account needs the Virtual Machine Contributor and Managed Identity Operator role assignments. No additional Azure AD directory role assignments are required.

  1. Sign in to Azure using Connect-AzAccount. Use an account that is associated with the Azure subscription that contains the VM.

    Connect-AzAccount
    
  2. Create a user-assigned managed identity using the New-AzUserAssignedIdentity cmdlet. Note the Id in the output because you will need this in the next step.

    Important

    Creating user-assigned managed identities only supports alphanumeric, underscore and hyphen (0-9 or a-z or A-Z, _ or -) characters. Additionally, name should be limited from 3 to 128 character length for the assignment to VM/VMSS to work properly. For more information see FAQs and known issues

    New-AzUserAssignedIdentity -ResourceGroupName <RESOURCEGROUP> -Name <USER ASSIGNED IDENTITY NAME>
    
  3. Retrieve the VM properties using the Get-AzVM cmdlet. Then to assign a user-assigned managed identity to the Azure VM, use the -IdentityType and -IdentityID switch on the Update-AzVM cmdlet. The value for the-IdentityId parameter is the Id you noted in the previous step. Replace <VM NAME>, <SUBSCRIPTION ID>, <RESROURCE GROUP>, and <USER ASSIGNED IDENTITY NAME> with your own values.

    Warning

    To retain any previously user-assigned managed identities assigned to the VM, query the Identity property of the VM object (for example, $vm.Identity). If any user assigned managed identities are returned, include them in the following command along with the new user assigned managed identity you would like to assign to the VM.

    $vm = Get-AzVM -ResourceGroupName <RESOURCE GROUP> -Name <VM NAME>
    Update-AzVM -ResourceGroupName <RESOURCE GROUP> -VM $vm -IdentityType UserAssigned -IdentityID "/subscriptions/<SUBSCRIPTION ID>/resourcegroups/<RESROURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>"
    

Note

You may optionally provision the managed identities for Azure resources VM extension, but it will soon be deprecated. We recommend using the Azure Instance Metadata identity endpoint for authentication. For more information, see Migrate from the VM extension to Azure IMDS endpoint for authentication.

Remove a user-assigned managed identity from an Azure VM

To remove a user-assigned identity to a VM, your account needs the Virtual Machine Contributor role assignment.

If your VM has multiple user-assigned managed identities, you can remove all but the last one using the following commands. Be sure to replace the <RESOURCE GROUP> and <VM NAME> parameter values with your own values. The <USER ASSIGNED IDENTITY NAME> is the user-assigned managed identity's name property, which should remain on the VM. This information can be found by querying the Identity property of the VM object. For example, $vm.Identity:

$vm = Get-AzVm -ResourceGroupName myResourceGroup -Name myVm
Update-AzVm -ResourceGroupName myResourceGroup -VirtualMachine $vm -IdentityType UserAssigned -IdentityID <USER ASSIGNED IDENTITY NAME>

If your VM does not have a system-assigned managed identity and you want to remove all user-assigned managed identities from it, use the following command:

$vm = Get-AzVm -ResourceGroupName myResourceGroup -Name myVm
Update-AzVm -ResourceGroupName myResourceGroup -VM $vm -IdentityType None

If your VM has both system-assigned and user-assigned managed identities, you can remove all the user-assigned managed identities by switching to use only system-assigned managed identities.

$vm = Get-AzVm -ResourceGroupName myResourceGroup -Name myVm
Update-AzVm -ResourceGroupName myResourceGroup -VirtualMachine $vm -IdentityType "SystemAssigned"

Next steps