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:

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 system-assigned managed identity enabled:

  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-AzureRmVMConfig cmdlet syntax. Be sure to add a -AssignIdentity:$SystemAssigned parameter to provision the VM with the system-assigned identity enabled, for example:

    $vmConfig = New-AzureRmVMConfig -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-AzureRmVMExtension 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-AzureRmVMExtension -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

If you need to enable a system-assigned managed identity on an existing Virtual Machine:

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

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

    $vm = Get-AzureRmVM -ResourceGroupName myResourceGroup -Name myVM
    Update-AzureRmVM -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-AzureRmVMExtension 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-AzureRmVMExtension -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.

Disable system-assigned managed identity from an Azure VM

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 Login-AzureRmAccount. Use an account that is associated with the Azure subscription that contains the VM.

    Login-AzureRmAccount
    
  2. Retrieve the VM properties using the Get-AzureRmVM cmdlet and set the -IdentityType parameter to UserAssigned:

    $vm = Get-AzureRmVM -ResourceGroupName myResourceGroup -Name myVM    
    Update-AzureRmVm -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-AzureRmVM -ResourceGroupName myResourceGroup -Name myVM
Update-AzureRmVm -ResourceGroupName myResourceGroup -VM $vm -IdentityType None

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

Remove-AzureRmVMExtension -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 managed identity to an Azure VM when creating the VM:

  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-AzureRmVMConfig 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-AzureRmVMConfig -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-AzureRmVMExtension 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-AzureRmVMExtension -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 managed identity to an existing Azure VM:

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

    Connect-AzureRmAccount
    
  2. Create a user-assigned managed identity using the New-AzureRmUserAssignedIdentity 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-AzureRmUserAssignedIdentity -ResourceGroupName <RESOURCEGROUP> -Name <USER ASSIGNED IDENTITY NAME>
    
  3. Retrieve the VM properties using the Get-AzureRmVM cmdlet. Then to assign a user-assigned managed identity to the Azure VM, use the -IdentityType and -IdentityID switch on the Update-AzureRmVM 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.

    $vm = Get-AzureRmVM -ResourceGroupName <RESOURCE GROUP> -Name <VM NAME>
    Update-AzureRmVM -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-AzureRmVMExtension 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-AzureRmVMExtension -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

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 in the identity section of the VM using az vm show:

$vm = Get-AzureRmVm -ResourceGroupName myResourceGroup -Name myVm
Update-AzureRmVm -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-AzureRmVm -ResourceGroupName myResourceGroup -Name myVm
Update-AzureRmVm -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-AzureRmVm -ResourceGroupName myResourceGroup -Name myVm
Update-AzureRmVm -ResourceGroupName myResourceGroup -VirtualMachine $vm -IdentityType "SystemAssigned"

Next steps