Manage user-assigned managed identities

  • Article

Managed identities for Azure resources eliminate the need to manage credentials in code. You can use them to get a Microsoft Entra token for your applications. The applications can use the token when accessing resources that support Microsoft Entra authentication. Azure manages the identity so you don't have to.

There are two types of managed identities: system-assigned and user-assigned. System-assigned managed identities have their lifecycle tied to the resource that created them. This identity is restricted to only one resource, and you can grant permissions to the managed identity by using Azure role-based access control (RBAC). 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

Tip

Steps in this article might vary slightly based on the portal you start from.

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

  1. Sign in to the Azure portal.

  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, China North.
    • 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.

  4. Select Review + create to review the changes.

  5. Select Create.

List user-assigned managed identities

To list or read a user-assigned managed identity, your account needs to have either Managed Identity Operator or Managed Identity Contributor role assignments.

  1. Sign in to the Azure portal.

  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.

  4. You can now view the details about the managed identity as shown in the image.

    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.

  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.

Manage access to user-assigned managed identities

In some environments, administrators choose to limit who can manage user-assigned managed identities. Administrators can implement this limitation using built-in RBAC roles. You can use these roles to grant a user or group in your organization rights over a user-assigned managed identity.

  1. Sign in to the Azure portal.

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

  4. Select Access control (IAM).

  5. Choose Add role assignment.

    Screenshot that shows the user-assigned managed identity access control screen.

  6. In the Add role assignment pane, choose the role to assign and choose Next.

  7. Choose who should have the role assigned.

Note

You can find information on assigning roles to managed identities in Assign a managed identity access to a resource by using the Azure portal

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

  • If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

    • 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 other sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install the Azure CLI extension 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 Microsoft Entra ID, 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.

Learn how to use workload identity federation for managed identities to access Microsoft Entra protected resources without managing secrets.

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:

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

  2. Sign in to Azure.

    Connect-AzAccount -Environment AzureChinaCloud

  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.

Learn how to use workload identity federation for managed identities to access Microsoft Entra protected resources without managing secrets.

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

Resource Manager templates help you 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

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

Learn how to use workload identity federation for managed identities to access Microsoft Entra protected resources without managing secrets.

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.chinacloudapi.cn/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.chinacloudapi.cn/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.chinacloudapi.cn/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities?api-version=2015-08-31-preview' -H "Authorization: Bearer <ACCESS TOKEN>"

GET https://management.chinacloudapi.cn/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.chinacloudapi.cn/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.chinacloudapi.cn/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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:

Learn how to use workload identity federation for managed identities to access Microsoft Entra protected resources without managing secrets.