Configure a VM Managed Service Identity (MSI) using PowerShell

Managed Service Identity (MSI) is a public preview feature of Azure Active Directory. Make sure you review the known issues before you begin. For more information about previews, see Supplemental Terms of Use for Microsoft Azure Previews.

Managed Service Identity 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, you learn how to perform the following Managed Service Identity operations on an Azure VM, using PowerShell:

System assigned identity

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

Enable system assigned identity during creation of an Azure VM

To create an Azure VM with the system assigned 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 MSI 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:

    $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.

Enable system assigned identity on an existing Azure VM

If you need to enable a system assigned 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. Also make sure your account belongs to a role that gives you write permissions on the VM, such as “Virtual Machine Contributor”:

    Login-AzureRmAccount
    
  2. First retrieve the VM properties using the Get-AzureRmVM cmdlet. Then to enable a system assigned 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 MSI 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:

    $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 the system assigned identity from an Azure VM

Note

Disabling Managed Service Identity from a Virtual Machine is currently not supported. In the meantime, you can switch between using System Assigned and User Assigned Identities.

If you have a Virtual Machine that no longer needs the system assigned identity but still needs user assigned 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. Also make sure your account belongs to a role that gives you write permissions on the VM, such as “Virtual Machine Contributor”:

    Login-AzureRmAccount
    
  2. Run the following cmdlet:

    Update-AzureRmVm -ResourceGroupName myResourceGroup -Name myVm -IdentityType "UserAssigned"
    

    To remove the MSI 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 identity

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

Assign a user assigned identity to a VM during creation

To assign a user assigned 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 <MSI 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/<MSI NAME>..."
    
  2. (Optional) Add the MSI 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.

    $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 identity to an existing Azure VM

To assign a user assigned 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. Also make sure your account belongs to a role that gives you write permissions on the VM, such as “Virtual Machine Contributor”:

    Connect-AzureRmAccount
    
  2. Create a user assigned 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 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>
  1. Retrieve the VM properties using the Get-AzureRmVM cmdlet. Then to assign a user assigned 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>"
    
  2. Add the MSI 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. 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

Note

Removing all user assigned identities from a Virtual Machine is currently not supported, unless you have a system assigned identity. Check back for updates.

If your VM has multiple user assigned 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 <MSI NAME> is the user assigned identity's name property, which should remain on the VM. This information can be found by in the identity section of the VM using az vm show:

$vm = Get-AzureRmVm -ResourceGroupName myResourceGroup -Name myVm
$vm.Identity.IdentityIds = "<MSI NAME>"
Update-AzureRmVm -ResourceGroupName myResourceGroup -Name myVm -VirtualMachine $vm

If your VM has both system assigned and user assigned identities, you can remove all the user assigned identities by switching to use only system assigned. Use the following command:

$vm = Get-AzureRmVm -ResourceGroupName myResourceGroup -Name myVm
$vm.Identity.IdentityIds = $null
Update-AzureRmVm -ResourceGroupName myResourceGroup -Name myVm -VirtualMachine $vm -IdentityType "SystemAssigned"