Understand Azure role definitions

If you are trying to understand how an Azure role works or if you are creating your own Azure custom role, it's helpful to understand how roles are defined. This article describes the details of role definitions and provides some examples.

Role definition

A role definition is a collection of permissions. It's sometimes just called a role. A role definition lists the actions that can be performed, such as read, write, and delete. It can also list the actions that are excluded from allowed actions or actions related to underlying data.

The following shows an example of the properties in a role definition when displayed using Azure PowerShell:

Name
Id
IsCustom
Description
Actions []
NotActions []
DataActions []
NotDataActions []
AssignableScopes []
Condition
ConditionVersion

The following shows an example of the properties in a role definition when displayed using the Azure CLI or REST API:

roleName
name
id
roleType
type
description
actions []
notActions []
dataActions []
notDataActions []
assignableScopes []
condition
conditionVersion
createdOn
updatedOn
createdBy
updatedBy

The following table describes what the role properties mean.

Property	Description
Name roleName	Display name of the role.
Id name	Unique ID of the role. Built-in roles have the same role ID across clouds.
id	Fully qualified unique ID of the role. Even if the role is renamed, the role ID does not change. It's a best practice to use the role ID in your scripts.
IsCustom roleType	Indicates whether this role is a custom role. Set to true or CustomRole for custom roles. Set to false or BuiltInRole for built-in roles.
type	Type of object. Set to Microsoft.Authorization/roleDefinitions.
Description description	Description of the role.
Actions actions	Array of strings that specifies the control plane actions that the role allows to be performed.
NotActions notActions	Array of strings that specifies the control plane actions that are excluded from the allowed Actions.
DataActions dataActions	Array of strings that specifies the data plane actions that the role allows to be performed to your data within that object.
NotDataActions notDataActions	Array of strings that specifies the data plane actions that are excluded from the allowed DataActions.
AssignableScopes assignableScopes	Array of strings that specifies the scopes that the role is available for assignment.
Condition condition	For built-in roles, condition statement based on one or more actions in role definition.
ConditionVersion conditionVersion	Condition version number. Defaults to 2.0 and is the only supported version.
createdOn	Date and time role was created.
updatedOn	Date and time role was last updated.
createdBy	For custom roles, principal that created role.
updatedBy	For custom roles, principal that updated role.

Actions format

Actions are specified with strings that have the following format:

• {Company}.{ProviderName}/{resourceType}/{action}

The {action} portion of an action string specifies the type of actions you can perform on a resource type. For example, you will see the following substrings in {action}:

Action substring	Description
*	The wildcard character grants access to all actions that match the string.
read	Enables read actions (GET).
write	Enables write actions (PUT or PATCH).
action	Enables custom actions like restart virtual machines (POST).
delete	Enables delete actions (DELETE).

Role definition example

Here's the Contributor role definition as displayed in Azure PowerShell and Azure CLI. The wildcard (*) actions under Actions indicates that the principal assigned to this role can perform all actions, or in other words, it can manage everything. This includes actions defined in the future, as Azure adds new resource types. The actions under NotActions are subtracted from Actions. In the case of the Contributor role, NotActions removes this role's ability to manage access to resources and also manage Azure Blueprints assignments.

Contributor role as displayed in Azure PowerShell:

{
  "Name": "Contributor",
  "Id": "b24988ac-6180-42a0-ab88-20f7382dd24c",
  "IsCustom": false,
  "Description": "Grants full access to manage all resources, but does not allow you to assign roles in Azure RBAC, manage assignments in Azure Blueprints, or share image galleries.",
  "Actions": [
    "*"
  ],
  "NotActions": [
    "Microsoft.Authorization/*/Delete",
    "Microsoft.Authorization/*/Write",
    "Microsoft.Authorization/elevateAccess/Action",
    "Microsoft.Blueprint/blueprintAssignments/write",
    "Microsoft.Blueprint/blueprintAssignments/delete",
    "Microsoft.Compute/galleries/share/action",
    "Microsoft.Purview/consents/write",
    "Microsoft.Purview/consents/delete"
  ],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/"
  ],
  "Condition": null,
  "ConditionVersion": null
}

Contributor role as displayed in Azure CLI:

[
  {
    "assignableScopes": [
      "/"
    ],
    "createdBy": null,
    "createdOn": "2015-02-02T21:55:09.880642+00:00",
    "description": "Grants full access to manage all resources, but does not allow you to assign roles in Azure RBAC, manage assignments in Azure Blueprints, or share image galleries.",
    "id": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c",
    "name": "b24988ac-6180-42a0-ab88-20f7382dd24c",
    "permissions": [
      {
        "actions": [
          "*"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [],
        "notActions": [
          "Microsoft.Authorization/*/Delete",
          "Microsoft.Authorization/*/Write",
          "Microsoft.Authorization/elevateAccess/Action",
          "Microsoft.Blueprint/blueprintAssignments/write",
          "Microsoft.Blueprint/blueprintAssignments/delete",
          "Microsoft.Compute/galleries/share/action",
          "Microsoft.Purview/consents/write",
          "Microsoft.Purview/consents/delete"
        ],
        "notDataActions": []
      }
    ],
    "roleName": "Contributor",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
    "updatedBy": null,
    "updatedOn": "2023-07-10T15:10:53.947865+00:00"
  }
]

Control and data actions

Role-based access control for control plane actions is specified in the Actions and NotActions properties of a role definition. Here are some examples of control plane actions in Azure:

• Manage access to a storage account
• Create, update, or delete a blob container
• Delete a resource group and all of its resources

Control plane access is not inherited to your data plane provided that the container authentication method is set to Microsoft Entra User Account and not Access Key. This separation prevents roles with wildcards (*) from having unrestricted access to your data. For example, if a user has a Reader role on a subscription, then they can view the storage account, but by default they can't view the underlying data.

Previously, role-based access control was not used for data actions. Authorization for data actions varied across resource providers. The same role-based access control authorization model used for control plane actions has been extended to data plane actions.

To support data plane actions, new data properties have been added to the role definition. Data plane actions are specified in the DataActions and NotDataActions properties. By adding these data properties, the separation between control plane and data plane is maintained. This prevents current role assignments with wildcards (*) from suddenly having accessing to data. Here are some data plane actions that can be specified in DataActions and NotDataActions:

• Read a list of blobs in a container
• Write a storage blob in a container
• Delete a message in a queue

Here's the Storage Blob Data Reader role definition, which includes actions in both the Actions and DataActions properties. This role allows you to read the blob container and also the underlying blob data.

Storage Blob Data Reader role as displayed in Azure PowerShell:

{
  "Name": "Storage Blob Data Reader",
  "Id": "2a2b9908-6ea1-4ae2-8e65-a410df84e7d1",
  "IsCustom": false,
  "Description": "Allows for read access to Azure Storage blob containers and data",
  "Actions": [
    "Microsoft.Storage/storageAccounts/blobServices/containers/read",
    "Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action"
  ],
  "NotActions": [],
  "DataActions": [
    "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/"
  ],
  "Condition": null,
  "ConditionVersion": null
}

Storage Blob Data Reader role as displayed in Azure CLI:

[
  {
    "assignableScopes": [
      "/"
    ],
    "createdBy": null,
    "createdOn": "2017-12-21T00:01:24.797231+00:00",
    "description": "Allows for read access to Azure Storage blob containers and data",
    "id": "/subscriptions/{subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/2a2b9908-6ea1-4ae2-8e65-a410df84e7d1",
    "name": "2a2b9908-6ea1-4ae2-8e65-a410df84e7d1",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/storageAccounts/blobServices/containers/read",
          "Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action"
        ],
        "condition": null,
        "conditionVersion": null,
        "dataActions": [
          "Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read"
        ],
        "notActions": [],
        "notDataActions": []
      }
    ],
    "roleName": "Storage Blob Data Reader",
    "roleType": "BuiltInRole",
    "type": "Microsoft.Authorization/roleDefinitions",
    "updatedBy": null,
    "updatedOn": "2021-11-11T20:13:55.297507+00:00"
  }
]

Only data plane actions can be added to the DataActions and NotDataActions properties. Resource providers identify which actions are data actions, by setting the isDataAction property to true. To see a list of the actions where isDataAction is true, see Resource provider operations. Roles that do not have data actions are not required to have DataActions and NotDataActions properties within the role definition.

Authorization for all control plane API calls is handled by Azure Resource Manager. Authorization for data plane API calls is handled by either a resource provider or Azure Resource Manager.

Data actions example

To better understand how control plane and data plane actions work, let's consider a specific example. Alice has been assigned the Owner role at the subscription scope. Bob has been assigned the Storage Blob Data Contributor role at a storage account scope. The following diagram shows this example.

The Owner role for Alice and the Storage Blob Data Contributor role for Bob have the following actions:

Owner

    Actions
    *

Storage Blob Data Contributor

    Actions
    Microsoft.Storage/storageAccounts/blobServices/containers/delete
    Microsoft.Storage/storageAccounts/blobServices/containers/read
    Microsoft.Storage/storageAccounts/blobServices/containers/write
    Microsoft.Storage/storageAccounts/blobServices/generateUserDelegationKey/action
    DataActions
    Microsoft.Storage/storageAccounts/blobServices/containers/blobs/delete
    Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
    Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
    Microsoft.Storage/storageAccounts/blobServices/containers/blobs/move/action
    Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action

Since Alice has a wildcard (*) action at a subscription scope, their permissions inherit down to enable them to perform all control plane actions. Alice can read, write, and delete containers. However, Alice cannot perform data plane actions without taking additional steps. For example, by default, Alice cannot read the blobs inside a container. To read the blobs, Alice would have to retrieve the storage access keys and use them to access the blobs.

Bob's permissions are restricted to just the Actions and DataActions specified in the Storage Blob Data Contributor role. Based on the role, Bob can perform both control plane and data plane actions. For example, Bob can read, write, and delete containers in the specified storage account and can also read, write, and delete the blobs.

For more information about control and data plane security for storage, see the Azure Storage security guide.

What tools support using Azure roles for data actions?

To view and work with data actions, you must have the correct versions of the tools or SDKs:

Tool	Version
Azure PowerShell	1.1.0 or later
Azure CLI	2.0.30 or later
Azure for .NET	2.8.0-preview or later
Azure SDK for Go	15.0.0 or later
Azure for Java	1.9.0 or later
Azure for Python	0.40.0 or later
Azure SDK for Ruby	0.17.1 or later

To view and use the data actions in the REST API, you must set the api-version parameter to the following version or later:

• 2018-07-01

Actions

The Actions permission specifies the control plane actions that the role allows to be performed. It is a collection of strings that identify securable actions of Azure resource providers. Here are some examples of control plane actions that can be used in Actions.

NotActions

The NotActions permission specifies the control plane actions that are subtracted or excluded from the allowed Actions that have a wildcard (*). Use the NotActions permission if the set of actions that you want to allow is more easily defined by subtracting from Actions that have a wildcard (*). The access granted by a role (effective permissions) is computed by subtracting the NotActions actions from the Actions actions.

Actions - NotActions = Effective control plane permissions

Differences between NotActions and deny assignments

NotActions and deny assignments are not the same and serve different purposes. NotActions are a convenient way to subtract specific actions from a wildcard (*) action.

Deny assignments block users from performing specific actions even if a role assignment grants them access. For more information, see Understand Azure deny assignments.

DataActions

The DataActions permission specifies the data plane actions that the role allows to be performed to your data within that object. For example, if a user has read blob data access to a storage account, then they can read the blobs within that storage account. Here are some examples of data actions that can be used in DataActions.

NotDataActions

The NotDataActions permission specifies the data plane actions that are subtracted or excluded from the allowed DataActions that have a wildcard (*). Use the NotDataActions permission if the set of actions that you want to allow is more easily defined by subtracting from DataActions that have a wildcard (*). The access granted by a role (effective permissions) is computed by subtracting the NotDataActions actions from the DataActions actions. Each resource provider provides its respective set of APIs to fulfill data actions.

DataActions - NotDataActions = Effective data plane permissions

The following table shows two examples of the effective date plane permissions for a Microsoft.Storage wildcard action:

AssignableScopes

The AssignableScopes property specifies the scopes (root, management group, subscriptions, or resource groups) where a role definition can be assigned. You can make a custom role available for assignment in only the management group, subscriptions, or resource groups that require it. You must use at least one management group, subscription, or resource group.

For example, if AssignableScopes is set to a subscription, that means that the custom role is available for assignment at subscription scope for the specified subscription, resource group scope for any resource group in the subscription, or resource scope for any resource in the subscription.

Built-in roles have AssignableScopes set to the root scope ("/"). The root scope indicates that the role is available for assignment in all scopes.

Examples of valid assignable scopes include:

You can define only one management group in AssignableScopes of a custom role.

Although it's possible to create a custom role with a resource instance in AssignableScopes using the command line, it's not recommended. Each tenant supports a maximum of 5,000 custom roles. Using this strategy could potentially exhaust your available custom roles. Ultimately, the level of access is determined by the custom role assignment (scope + role permissions + security principal) and not the AssignableScopes listed in the custom role. So, create your custom roles with AssignableScopes of management group, subscription, or resource group, but assign the custom roles with narrow scope, such as resource or resource group.

For more information about AssignableScopes for custom roles, see Azure custom roles.

Privileged administrator role definition

Privileged administrator roles are roles that grant privileged administrator access, such as the ability to manage Azure resources or assign roles to other users. If a built-in or custom role includes any of the following actions, it is considered privileged. For more information, see List or manage privileged administrator role assignments.

Next steps

• Understand role assignments
• Azure built-in roles
• Azure custom roles
• Azure resource provider operations