Manage access to Azure resources using RBAC and Azure CLI

Role-based access control (RBAC) is the way that you manage access to Azure resources. This article describes how you manage access for users, groups, and applications using RBAC and Azure CLI.

Prerequisites

To manage access, you need one of the following:

List roles

To list all available role definitions, use az role definition list:

az role definition list

The following example lists the name and description of all available role definitions:

az role definition list --output json | jq '.[] | {"roleName":.roleName, "description":.description}'
{
  "roleName": "API Management Service Contributor",
  "description": "Can manage service and the APIs"
}
{
  "roleName": "API Management Service Operator Role",
  "description": "Can manage service but not the APIs"
}
{
  "roleName": "API Management Service Reader Role",
  "description": "Read-only access to service and APIs"
}

...

The following example lists all of the built-in role definitions:

az role definition list --custom-role-only false --output json | jq '.[] | {"roleName":.roleName, "description":.description, "roleType":.roleType}'
{
  "roleName": "API Management Service Contributor",
  "description": "Can manage service and the APIs",
  "roleType": "BuiltInRole"
}
{
  "roleName": "API Management Service Operator Role",
  "description": "Can manage service but not the APIs",
  "roleType": "BuiltInRole"
}
{
  "roleName": "API Management Service Reader Role",
  "description": "Read-only access to service and APIs",
  "roleType": "BuiltInRole"
}

...

List a role definition

To list a role definition, use az role definition list:

az role definition list --name <role_name>

The following example lists the Contributor role definition:

az role definition list --name "Contributor"
[
  {
    "additionalProperties": {},
    "assignableScopes": [
      "/"
    ],
    "description": "Lets you manage everything except access to resources.",
    "id": "/subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
    "name": "b24988ac-6180-42a0-ab88-20f7382dd24c",
    "permissions": [
      {
        "actions": [
          "*"
        ],
        "additionalProperties": {},
        "dataActions": [],
        "notActions": [
          "Microsoft.Authorization/*/Delete",
          "Microsoft.Authorization/*/Write",
          "Microsoft.Authorization/elevateAccess/Action"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Contributor",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions"
  }
]

List actions of a role

The following example lists just the actions and notActions of the Contributor role:

az role definition list --name "Contributor" --output json | jq '.[] | {"actions":.permissions[0].actions, "notActions":.permissions[0].notActions}'
{
  "actions": [
    "*"
  ],
  "notActions": [
    "Microsoft.Authorization/*/Delete",
    "Microsoft.Authorization/*/Write",
    "Microsoft.Authorization/elevateAccess/Action"
  ]
}

The following example lists just the actions of the Virtual Machine Contributor role:

az role definition list --name "Virtual Machine Contributor" --output json | jq '.[] | .permissions[0].actions'
[
  "Microsoft.Authorization/*/read",
  "Microsoft.Compute/availabilitySets/*",
  "Microsoft.Compute/locations/*",
  "Microsoft.Compute/virtualMachines/*",
  "Microsoft.Compute/virtualMachineScaleSets/*",
  "Microsoft.Insights/alertRules/*",
  "Microsoft.Network/applicationGateways/backendAddressPools/join/action",
  "Microsoft.Network/loadBalancers/backendAddressPools/join/action",

  ...

  "Microsoft.Storage/storageAccounts/listKeys/action",
  "Microsoft.Storage/storageAccounts/read"
]

List access

In RBAC, to list access, you list the role assignments.

List role assignments for a user

To list the role assignments for a specific user, use az role assignment list:

az role assignment list --assignee <assignee>

By default, only direct assignments scoped to subscription will be displayed. To view assignments scoped by resource or group, use --all and to view inherited asisgnments, use --include-inherited.

The following example lists the role assignments that are assigned directly to the patlong@contoso.com user:

az role assignment list --all --assignee patlong@contoso.com --output json | jq '.[] | {"principalName":.principalName, "roleDefinitionName":.roleDefinitionName, "scope":.scope}'
{
  "principalName": "patlong@contoso.com",
  "roleDefinitionName": "Backup Operator",
  "scope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales"
}
{
  "principalName": "patlong@contoso.com",
  "roleDefinitionName": "Virtual Machine Contributor",
  "scope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales"
}

List role assignments for a resource group

To list the role assignments that exist for a resource group, use az role assignment list:

az role assignment list --resource-group <resource_group>

The following example lists the role assignments for the pharma-sales resource group:

az role assignment list --resource-group pharma-sales --output json | jq '.[] | {"roleDefinitionName":.roleDefinitionName, "scope":.scope}'
{
  "roleDefinitionName": "Backup Operator",
  "scope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales"
}
{
  "roleDefinitionName": "Virtual Machine Contributor",
  "scope": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/pharma-sales"
}

...

Grant access

In RBAC, to grant access, you create a role assignment.

Create a role assignment for a user

To create a role assignment for a user at the resource group scope, use az role assignment create:

az role assignment create --role <role_name_or_id> --assignee <assignee> --resource-group <resource_group>

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

Create a role assignment 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 create a role assignment using the unique role ID instead of the role name, use az role assignment create.

az role assignment create --role <role_id> --assignee <assignee> --resource-group <resource_group>

The following example assigns the Virtual Machine Contributor role to 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 Built-in roles for Azure resources.

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

Create a role assignment for a group

To create a role assignment for a group, use az role assignment create:

az role assignment create --role <role_name_or_id> --assignee-object-id <assignee_object_id> --resource-group <resource_group> --scope </subscriptions/subscription_id>

The following example assigns the Reader role to the Ann Mack Team group with ID 22222222-2222-2222-2222-222222222222 at the subscription scope. To get the ID of the group, you can use az ad group list or az ad group show.

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

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

Create a role assignment for an application

To create a role for an application, use az role assignment create:

az role assignment create --role <role_name_or_id> --assignee-object-id <assignee_object_id> --resource-group <resource_group> --scope </subscriptions/subscription_id>

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. To get the object ID of the application, you can use az ad app list or az ad app show.

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

Remove access

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

az role assignment delete --assignee <assignee> --role <role_name_or_id> --resource-group <resource_group>

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 the subscription scope. To get the ID of the group, you can use az ad group list or az ad group show.

az role assignment delete --assignee 22222222-2222-2222-2222-222222222222 --role "Reader" --scope /subscriptions/00000000-0000-0000-0000-000000000000

Next steps