Manage user-assigned managed identities

Managed identities for Azure resources eliminate the need to manage credentials in code. You can use them to get an Azure Active Directory (Azure AD) token your applications can use when you access resources that support Azure AD authentication. Azure manages the identity so you don't have to.

There are two types of managed identities: system-assigned and user-assigned. The main difference between them is that system-assigned managed identities have their lifecycle linked to the resource where they're used. User-assigned managed identities can be used on multiple resources. To learn more about managed identities, see What are managed identities for Azure resources?.

In this article, you learn how to create, list, delete, or assign a role to a user-assigned managed identity by using the Azure portal.

Prerequisites

Create a user-assigned managed identity

To create a user-assigned managed identity, your account needs the Managed Identity Contributor role assignment.

  1. Sign in to the Azure portal by using an account associated with the Azure subscription to create the user-assigned managed identity.
  2. In the search box, enter Managed Identities. Under Services, select Managed Identities.
  3. Select Add, and enter values in the following boxes in the Create User Assigned Managed Identity pane:
    • Subscription: Choose the subscription to create the user-assigned managed identity under.
    • Resource group: Choose a resource group to create the user-assigned managed identity in, or select Create new to create a new resource group.
    • Region: Choose a region to deploy the user-assigned managed identity, for example, West US.
    • Name: Enter the name for your user-assigned managed identity, for example, UAI1.

Important

When you create user-assigned managed identities, only alphanumeric characters (0-9, a-z, and A-Z) and the hyphen (-) are supported. For the assignment to a virtual machine or virtual machine scale set to work properly, the name is limited to 24 characters. For more information, see FAQs and known issues.

Screenshot that shows the Create User Assigned Managed Identity pane.

  1. Select Review + create to review the changes.
  2. Select Create.

List user-assigned managed identities

To list or read a user-assigned managed identity, your account needs the Managed Identity Operator or Managed Identity Contributor role assignment.

  1. Sign in to the Azure portal by using an account associated with the Azure subscription to list the user-assigned managed identities.

  2. In the search box, enter Managed Identities. Under Services, select Managed Identities.

  3. A list of the user-assigned managed identities for your subscription is returned. To see the details of a user-assigned managed identity, select its name.

    Screenshot that shows the list of user-assigned managed identity.

Delete a user-assigned managed identity

To delete a user-assigned managed identity, your account needs the Managed Identity Contributor role assignment.

Deleting a user-assigned identity doesn't remove it from the VM or resource it was assigned to. To remove the user-assigned identity from a VM, see Remove a user-assigned managed identity from a VM.

  1. Sign in to the Azure portal by using an account associated with the Azure subscription to delete a user-assigned managed identity.

  2. Select the user-assigned managed identity, and select Delete.

  3. Under the confirmation box, select Yes.

    Screenshot that shows the Delete user-assigned managed identities.

Assign a role to a user-assigned managed identity

To assign a role to a user-assigned managed identity, your account needs the User Access Administrator role assignment.

  1. Sign in to the Azure portal by using an account associated with the Azure subscription to list the user-assigned managed identities.

  2. In the search box, enter Managed Identities. Under Services, select Managed Identities.

  3. A list of the user-assigned managed identities for your subscription is returned. Select the user-assigned managed identity that you want to assign a role.

  4. Select Access control (IAM), and then select Add role assignment.

    Screenshot that shows the user-assigned managed identity start.

  5. In the Add role assignment pane, configure the following values, and then select Save:

    • Role: The role to assign.
    • Assign access to: The resource to assign the user-assigned managed identity.
    • Select: The member to assign access.

    Screenshot that shows the user-assigned managed identity IAM.

In this article, you learn how to create, list, delete, or assign a role to a user-assigned managed identity by using the Azure CLI.

Prerequisites

  • Use the Bash environment in Azure Cloud Shell.

    Launch Cloud Shell in a new window

  • If you prefer, install the Azure CLI to run CLI reference commands.

    • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For additional sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install Azure CLI extensions on first use. For more information about extensions, see Use extensions with the Azure CLI.

    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

Important

To modify user permissions when you use an app service principal by using the CLI, you must provide the service principal more permissions in the Azure Active Directory Graph API because portions of the CLI perform GET requests against the Graph API. Otherwise, you might end up receiving an "Insufficient privileges to complete the operation" message. To do this step, go into the App registration in Azure AD, select your app, select API permissions, and scroll down and select Azure Active Directory Graph. From there, select Application permissions, and then add the appropriate permissions.

Create a user-assigned managed identity

To create a user-assigned managed identity, your account needs the Managed Identity Contributor role assignment.

Use the az identity create command to create a user-assigned managed identity. The -g parameter specifies the resource group where to create the user-assigned managed identity. The -n parameter specifies its name. Replace the <RESOURCE GROUP> and <USER ASSIGNED IDENTITY NAME> parameter values with your own values.

Important

When you create user-assigned managed identities, only alphanumeric characters (0-9, a-z, and A-Z) and the hyphen (-) are supported. For the assignment to a virtual machine or virtual machine scale set to work properly, the name is limited to 24 characters. For more information, see FAQs and known issues.

az identity create -g <RESOURCE GROUP> -n <USER ASSIGNED IDENTITY NAME>

List user-assigned managed identities

To list or read a user-assigned managed identity, your account needs the Managed Identity Operator or Managed Identity Contributor role assignment.

To list user-assigned managed identities, use the az identity list command. Replace the <RESOURCE GROUP> value with your own value.

az identity list -g <RESOURCE GROUP>

In the JSON response, user-assigned managed identities have the "Microsoft.ManagedIdentity/userAssignedIdentities" value returned for the key type.

"type": "Microsoft.ManagedIdentity/userAssignedIdentities"

Delete a user-assigned managed identity

To delete a user-assigned managed identity, your account needs the Managed Identity Contributor role assignment.

To delete a user-assigned managed identity, use the az identity delete command. The -n parameter specifies its name. The -g parameter specifies the resource group where the user-assigned managed identity was created. Replace the <USER ASSIGNED IDENTITY NAME> and <RESOURCE GROUP> parameter values with your own values.

az identity delete -n <USER ASSIGNED IDENTITY NAME> -g <RESOURCE GROUP>

Note

Deleting a user-assigned managed identity won't remove the reference from any resource it was assigned to. Remove those from a VM or virtual machine scale set by using the az vm/vmss identity remove command.

Next steps

For a full list of Azure CLI identity commands, see az identity.

For information on how to assign a user-assigned managed identity to an Azure VM, see Configure managed identities for Azure resources on an Azure VM using Azure CLI.

In this article, you learn how to create, list, delete, or assign a role to a user-assigned managed identity by using the PowerShell.

Prerequisites

In this article, you learn how to create, list, and delete a user-assigned managed identity by using PowerShell.

Configure Azure PowerShell locally

To use Azure PowerShell locally for this article instead of using Cloud Shell:

  1. Install the latest version of Azure PowerShell if you haven't already.

  2. Sign in to Azure.

    Connect-AzAccount
    
  3. Install the latest version of PowerShellGet.

    Install-Module -Name PowerShellGet -AllowPrerelease
    

    You might need to Exit out of the current PowerShell session after you run this command for the next step.

  4. Install the prerelease version of the Az.ManagedServiceIdentity module to perform the user-assigned managed identity operations in this article.

    Install-Module -Name Az.ManagedServiceIdentity -AllowPrerelease
    

Create a user-assigned managed identity

To create a user-assigned managed identity, your account needs the Managed Identity Contributor role assignment.

To create a user-assigned managed identity, use the New-AzUserAssignedIdentity command. The ResourceGroupName parameter specifies the resource group where to create the user-assigned managed identity. The -Name parameter specifies its name. Replace the <RESOURCE GROUP> and <USER ASSIGNED IDENTITY NAME> parameter values with your own values.

Important

When you create user-assigned managed identities, only alphanumeric characters (0-9, a-z, and A-Z) and the hyphen (-) are supported. For the assignment to a virtual machine or virtual machine scale set to work properly, the name is limited to 24 characters. For more information, see FAQs and known issues.

New-AzUserAssignedIdentity -ResourceGroupName <RESOURCEGROUP> -Name <USER ASSIGNED IDENTITY NAME>

List user-assigned managed identities

To list or read a user-assigned managed identity, your account needs the Managed Identity Operator or Managed Identity Contributor role assignment.

To list user-assigned managed identities, use the [Get-AzUserAssigned] command. The -ResourceGroupName parameter specifies the resource group where the user-assigned managed identity was created. Replace the <RESOURCE GROUP> value with your own value.

Get-AzUserAssignedIdentity -ResourceGroupName <RESOURCE GROUP>

In the response, user-assigned managed identities have the "Microsoft.ManagedIdentity/userAssignedIdentities" value returned for the key Type.

Type :Microsoft.ManagedIdentity/userAssignedIdentities

Delete a user-assigned managed identity

To delete a user-assigned managed identity, your account needs the Managed Identity Contributor role assignment.

To delete a user-assigned managed identity, use the Remove-AzUserAssignedIdentity command. The -ResourceGroupName parameter specifies the resource group where the user-assigned identity was created. The -Name parameter specifies its name. Replace the <RESOURCE GROUP> and the <USER ASSIGNED IDENTITY NAME> parameter values with your own values.

Remove-AzUserAssignedIdentity -ResourceGroupName <RESOURCE GROUP> -Name <USER ASSIGNED IDENTITY NAME>

Note

Deleting a user-assigned managed identity won't remove the reference from any resource it was assigned to. Identity assignments must be removed separately.

Next steps

For a full list and more details of the Azure PowerShell managed identities for Azure resources commands, see Az.ManagedServiceIdentity.

In this article, you create a user-assigned managed identity by using Azure Resource Manager.

Prerequisites

You can't list and delete a user-assigned managed identity by using a Resource Manager template. See the following articles to create and list a user-assigned managed identity:

Template creation and editing

As with the Azure portal and scripting, Resource Manager templates provide the ability to deploy new or modified resources defined by an Azure resource group. Several options are available for template editing and deployment, both local and portal-based. You can:

Create a user-assigned managed identity

To create a user-assigned managed identity, your account needs the Managed Identity Contributor role assignment.

To create a user-assigned managed identity, use the following template. Replace the <USER ASSIGNED IDENTITY NAME> value with your own values.

Important

When you create user-assigned managed identities, only alphanumeric characters (0-9, a-z, and A-Z) and the hyphen (-) are supported. For the assignment to a virtual machine or virtual machine scale set to work properly, the name is limited to 24 characters. For more information, see FAQs and known issues.

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "resourceName": {
          "type": "string",
          "metadata": {
            "description": "<USER ASSIGNED IDENTITY NAME>"
          }
        }
  },
  "resources": [
    {
      "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
      "name": "[parameters('resourceName')]",
      "apiVersion": "2018-11-30",
      "location": "[resourceGroup().location]"
    }
  ],
  "outputs": {
      "identityName": {
          "type": "string",
          "value": "[parameters('resourceName')]"
      }
  }
}

Next steps

For information on how to assign a user-assigned managed identity to an Azure VM by using a Resource Manager template, see Configure managed identities for Azure resources on an Azure VM using a template.

In this article, you learn how to create, list, and delete a user-assigned managed identity by using REST.

Prerequisites

In this article, you learn how to create, list, and delete a user-assigned managed identity by using CURL to make REST API calls.

Obtain a bearer access token

  1. If you're running locally, sign in to Azure through the Azure CLI.

    az login
    
  2. Obtain an access token by using az account get-access-token.

    az account get-access-token
    

Create a user-assigned managed identity

To create a user-assigned managed identity, your account needs the Managed Identity Contributor role assignment.

Important

When you create user-assigned managed identities, only alphanumeric characters (0-9, a-z, and A-Z) and the hyphen (-) are supported. For the assignment to a virtual machine or virtual machine scale set to work properly, the name is limited to 24 characters. For more information, see FAQs and known issues.

curl 'https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroup
s/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>?api-version=2015-08-31-preview' -X PUT -d '{"loc
ation": "<LOCATION>"}' -H "Content-Type: application/json" -H "Authorization: Bearer <ACCESS TOKEN>"
PUT https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroup
s/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>?api-version=2015-08-31-preview HTTP/1.1

Request headers

Request header Description
Content-Type Required. Set to application/json.
Authorization Required. Set to a valid Bearer access token.

Request body

Name Description
Location Required. Resource location.

List user-assigned managed identities

To list or read a user-assigned managed identity, your account needs the Managed Identity Operator or Managed Identity Contributor role assignment.

curl 'https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities?api-version=2015-08-31-preview' -H "Authorization: Bearer <ACCESS TOKEN>"
GET https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities?api-version=2015-08-31-preview HTTP/1.1
Request header Description
Content-Type Required. Set to application/json.
Authorization Required. Set to a valid Bearer access token.

Delete a user-assigned managed identity

To delete a user-assigned managed identity, your account needs the Managed Identity Contributor role assignment.

Note

Deleting a user-assigned managed identity won't remove the reference from any resource it was assigned to. To remove a user-assigned managed identity from a VM by using CURL, see Remove a user-assigned identity from an Azure VM.

curl 'https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroup
s/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>?api-version=2015-08-31-preview' -X DELETE -H "Authorization: Bearer <ACCESS TOKEN>"
DELETE https://management.azure.com/subscriptions/80c696ff-5efa-4909-a64d-f1b616f423ca/resourceGroups/TestRG/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<USER ASSIGNED IDENTITY NAME>?api-version=2015-08-31-preview HTTP/1.1
Request header Description
Content-Type Required. Set to application/json.
Authorization Required. Set to a valid Bearer access token.

Next steps

For information on how to assign a user-assigned managed identity to an Azure VM or virtual machine scale set by using CURL, see: