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. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For 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 ("Log 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 ...
    
  2. (Optional) Add the managed identities for Azure resources VM extension (planned for deprecation in January 2019) using the -Type parameter on the Set-AzVMExtension cmdlet. You can pass either "ManagedIdentityExtensionForWindows" or "ManagedIdentityExtensionForLinux", depending on the type of VM, and name it using the -Name parameter. The -Settings parameter specifies the port used by the OAuth token endpoint for token acquisition:

    $settings = @{ "port" = 50342 }
    Set-AzVMExtension -ResourceGroupName myResourceGroup -Location WestUS -VMName myVM -Name "ManagedIdentityExtensionForWindows" -Type "ManagedIdentityExtensionForWindows" -Publisher "Microsoft.ManagedIdentity" -TypeHandlerVersion "1.0" -Settings $settings 
    

    Note

    This step is optional as you can use the Azure Instance Metadata Service (IMDS) identity endpoint, to retrieve tokens as well. The managed identities for Azure resources VM extension is planned for deprecation in January 2019.

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
    
  3. (Optional) Add the managed identities for Azure resources VM extension (planned for deprecation in January 2019) using the -Type parameter on the Set-AzVMExtension cmdlet. You can pass either "ManagedIdentityExtensionForWindows" or "ManagedIdentityExtensionForLinux", depending on the type of VM, and name it using the -Name parameter. The -Settings parameter specifies the port used by the OAuth token endpoint for token acquisition. Be sure to specify the correct -Location parameter, matching the location of the existing VM:

    $settings = @{ "port" = 50342 }
    Set-AzVMExtension -ResourceGroupName myResourceGroup -Location WestUS -VMName myVM -Name "ManagedIdentityExtensionForWindows" -Type "ManagedIdentityExtensionForWindows" -Publisher "Microsoft.ManagedIdentity" -TypeHandlerVersion "1.0" -Settings $settings 
    

    Note

    This step is optional as you can use the Azure Instance Metadata Service (IMDS) identity endpoint, to retrieve tokens as well.

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

To remove the managed identities for Azure resources VM extension, user the -Name switch with the Remove-AzVMExtension cmdlet, specifying the same name you used when you added the extension:

Remove-AzVMExtension -ResourceGroupName myResourceGroup -Name "ManagedIdentityExtensionForWindows" -VMName myVM

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 ("Log 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>..."
    
  2. (Optional) Add the managed identity for Azure resources VM extension using the -Type parameter on the Set-AzVMExtension cmdlet. You can pass either "ManagedIdentityExtensionForWindows" or "ManagedIdentityExtensionForLinux", depending on the type of VM, and name it using the -Name parameter. The -Settings parameter specifies the port used by the OAuth token endpoint for token acquisition. Be sure to specify the correct -Location parameter, matching the location of the existing VM:

    Note

    This step is optional as you can use the Azure Instance Metadata Service (IMDS) identity endpoint, to retrieve tokens as well. The managed identities for Azure resources VM extension is planned for deprecation in January 2019.

    $settings = @{ "port" = 50342 }
    Set-AzVMExtension -ResourceGroupName myResourceGroup -Location WestUS -VMName myVM -Name "ManagedIdentityExtensionForWindows" -Type "ManagedIdentityExtensionForWindows" -Publisher "Microsoft.ManagedIdentity" -TypeHandlerVersion "1.0" -Settings $settings 
    

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 and hyphen (0-9 or a-z or A-Z or -) characters. Additionally, name should be limited to 24 character length for the assignment to VM/VMSS to work properly. Check back for updates. 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>"
    
  4. Add the managed identity for Azure resources VM extension (planned for deprecation in January 2019) using the -Type parameter on the Set-AzVMExtension cmdlet. You can pass either "ManagedIdentityExtensionForWindows" or "ManagedIdentityExtensionForLinux", depending on the type of VM, and name it using the -Name parameter. The -Settings parameter specifies the port used by the OAuth token endpoint for token acquisition. Specify the correct -Location parameter, matching the location of the existing VM.

    $settings = @{ "port" = 50342 }
    Set-AzVMExtension -ResourceGroupName myResourceGroup -Location WestUS -VMName myVM -Name "ManagedIdentityExtensionForWindows" -Type "ManagedIdentityExtensionForWindows" -Publisher "Microsoft.ManagedIdentity" -TypeHandlerVersion "1.0" -Settings $settings 
    

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