Add or remove Azure role assignments using Azure CLI

Azure role-based access control (Azure RBAC) is the authorization system you use to manage access to Azure resources. To grant access, you assign roles to users, groups, service principals, or managed identities at a particular scope. This article describes how to assign roles using Azure CLI.

Prerequisites

To add or remove role assignments, you must have:

Get object IDs

To add or remove role assignments, you might need to specify the unique ID of an object. The ID has the format: 11111111-1111-1111-1111-111111111111. You can get the ID using the Azure portal or Azure CLI.

User

To get the object ID for an Azure AD user, you can use az ad user show.

az ad user show --id "{email}" --query objectId --output tsv

Group

To get the object ID for an Azure AD group, you can use az ad group show or az ad group list.

az ad group show --group "{name}" --query objectId --output tsv

Application

To get the object ID for an Azure AD service principal (identity used by an application), you can use az ad sp list. For a service principal, use the object ID and not the application ID.

az ad sp list --display-name "{name}" --query [].objectId --output tsv

Add a role assignment

In Azure RBAC, to grant access, you add a role assignment.

User at a resource group scope

To add a role assignment for a user at a resource group scope, use az role assignment create.

az role assignment create --role {roleNameOrId} --assignee {assignee} --resource-group {resourceGroup}

The following example assigns the Virtual Machine Contributor role to patlong@contoso.com user at the pharma-sales resource group scope:

az role assignment create --role "Virtual Machine Contributor" --assignee patlong@contoso.com --resource-group pharma-sales

Using the unique role ID

There are a couple of times when a role name might change, for example:

  • You are using your own custom role and you decide to change the name.
  • You are using a preview role that has (Preview) in the name. When the role is released, the role is renamed.

Important

A preview version is provided without a service level agreement, and it's not recommended for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Even if a role is renamed, the role ID does not change. If you are using scripts or automation to create your role assignments, it's a best practice to use the unique role ID instead of the role name. Therefore, if a role is renamed, your scripts are more likely to work.

To add a role assignment using the unique role ID instead of the role name, use az role assignment create.

az role assignment create --role {roleId} --assignee {assignee} --resource-group {resourceGroup}

The following example assigns the Virtual Machine Contributor role to the patlong@contoso.com user at the pharma-sales resource group scope. To get the unique role ID, you can use az role definition list or see Azure built-in roles.

az role assignment create --role 9980e02c-c2be-4d73-94e8-173b1dc7cf3c --assignee patlong@contoso.com --resource-group pharma-sales

Group at a subscription scope

To add a role assignment for a group, use az role assignment create. For information about how to get the object ID of the group, see Get object IDs.

az role assignment create --role {roleNameOrId} --assignee-object-id {assigneeObjectId} --resource-group {resourceGroup} --scope /subscriptions/{subscriptionId}

The following example assigns the Reader role to the Ann Mack Team group with ID 22222222-2222-2222-2222-222222222222 at a subscription scope.

az role assignment create --role Reader --assignee-object-id 22222222-2222-2222-2222-222222222222 --scope /subscriptions/00000000-0000-0000-0000-000000000000

Group at a resource scope

To add a role assignment for a group, use az role assignment create. For information about how to get the object ID of the group, see Get object IDs.

The following example assigns the Virtual Machine Contributor role to the Ann Mack Team group with ID 22222222-2222-2222-2222-222222222222 at a resource scope for a virtual network named pharma-sales-project-network.

az role assignment create --role "Virtual Machine Contributor" --assignee-object-id 22222222-2222-2222-2222-222222222222 --scope /subscriptions/00000000-0000-0000-0000-000000000000/resourcegroups/pharma-sales/providers/Microsoft.Network/virtualNetworks/pharma-sales-project-network

Application at a resource group scope

To add a role assignment for an application, use az role assignment create. For information about how to get the object ID of the application, see Get object IDs.

az role assignment create --role {roleNameOrId} --assignee-object-id {assigneeObjectId} --resource-group {resourceGroup}

The following example assigns the Virtual Machine Contributor role to an application with object ID 44444444-4444-4444-4444-444444444444 at the pharma-sales resource group scope.

az role assignment create --role "Virtual Machine Contributor" --assignee-object-id 44444444-4444-4444-4444-444444444444 --resource-group pharma-sales

User at a subscription scope

To add a role assignment for a user at a subscription scope, use az role assignment create. To get the subscription ID, you can find it on the Subscriptions blade in the Azure portal or you can use az account list.

az role assignment create --role {roleNameOrId} --assignee {assignee} --subscription {subscriptionNameOrId}

The following example assigns the Reader role to the annm@example.com user at a subscription scope.

az role assignment create --role "Reader" --assignee annm@example.com --subscription 00000000-0000-0000-0000-000000000000

User at a management group scope

To add a role assignment for a user at a management group scope, use az role assignment create. To get the management group ID, you can find it on the Management groups blade in the Azure portal or you can use az account management-group list.

az role assignment create --role {roleNameOrId} --assignee {assignee} --scope /providers/Microsoft.Management/managementGroups/{groupId}

The following example assigns the Billing Reader role to the alain@example.com user at a management group scope.

az role assignment create --role "Billing Reader" --assignee alain@example.com --scope /providers/Microsoft.Management/managementGroups/marketing-group

New service principal

If you create a new service principal and immediately try to assign a role to that service principal, that role assignment can fail in some cases. For example, if you use a script to create a new managed identity and then try to assign a role to that service principal, the role assignment might fail. The reason for this failure is likely a replication delay. The service principal is created in one region; however, the role assignment might occur in a different region that hasn't replicated the service principal yet. To address this scenario, you should specify the principal type when creating the role assignment.

To add a role assignment, use az role assignment create, specify a value for --assignee-object-id, and then set --assignee-principal-type to ServicePrincipal.

az role assignment create --role {roleNameOrId} --assignee-object-id {assigneeObjectId} --assignee-principal-type {assigneePrincipalType} --resource-group {resourceGroup} --scope /subscriptions/{subscriptionId}

The following example assigns the Virtual Machine Contributor role to the msi-test managed identity at the pharma-sales resource group scope:

az role assignment create --role "Virtual Machine Contributor" --assignee-object-id 33333333-3333-3333-3333-333333333333 --assignee-principal-type ServicePrincipal --resource-group pharma-sales

Remove a role assignment

In Azure RBAC, to remove access, you remove a role assignment by using az role assignment delete:

az role assignment delete --assignee {assignee} --role {roleNameOrId} --resource-group {resourceGroup}

The following example removes the Virtual Machine Contributor role assignment from the patlong@contoso.com user on the pharma-sales resource group:

az role assignment delete --assignee patlong@contoso.com --role "Virtual Machine Contributor" --resource-group pharma-sales

The following example removes the Reader role from the Ann Mack Team group with ID 22222222-2222-2222-2222-222222222222 at a subscription scope. For information about how to get the object ID of the group, see Get object IDs.

az role assignment delete --assignee 22222222-2222-2222-2222-222222222222 --role "Reader" --subscription 00000000-0000-0000-0000-000000000000

The following example removes the Billing Reader role from the alain@example.com user at the management group scope. To get the ID of the management group, you can use az account management-group list.

az role assignment delete --assignee alain@example.com --role "Billing Reader" --scope /providers/Microsoft.Management/managementGroups/marketing-group

Next steps