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.
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 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). |
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"
}
]
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.
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.
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
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
.
Action string | Description |
---|---|
*/read |
Grants access to read actions for all resource types of all Azure resource providers. |
Microsoft.Compute/* |
Grants access to all actions for all resource types in the Microsoft.Compute resource provider. |
Microsoft.Network/*/read |
Grants access to read actions for all resource types in the Microsoft.Network resource provider. |
Microsoft.Compute/virtualMachines/* |
Grants access to all actions of virtual machines and its child resource types. |
microsoft.web/sites/restart/Action |
Grants access to restart a web app. |
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
The following table shows two examples of the effective control plane permissions for a Microsoft.CostManagement wildcard action:
Actions | NotActions | Effective control plane permissions |
---|---|---|
Microsoft.CostManagement/exports/* |
none | Microsoft.CostManagement/exports/action Microsoft.CostManagement/exports/read Microsoft.CostManagement/exports/write Microsoft.CostManagement/exports/delete Microsoft.CostManagement/exports/run/action |
Microsoft.CostManagement/exports/* |
Microsoft.CostManagement/exports/delete |
Microsoft.CostManagement/exports/action Microsoft.CostManagement/exports/read Microsoft.CostManagement/exports/write Microsoft.CostManagement/exports/run/action |
Σημείωση
If a user is assigned a role that excludes an action in NotActions
, and is assigned a second role that grants access to the same action, the user is allowed to perform that action. NotActions
is not a deny rule – it is simply a convenient way to create a set of allowed actions when specific actions need to be excluded.
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.
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
.
Data action string | Description |
---|---|
Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read |
Returns a blob or a list of blobs. |
Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write |
Returns the result of writing a blob. |
Microsoft.Storage/storageAccounts/queueServices/queues/messages/read |
Returns a message. |
Microsoft.Storage/storageAccounts/queueServices/queues/messages/* |
Returns a message or the result of writing or deleting a message. |
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:
DataActions | NotDataActions | Effective data plane permissions |
---|---|---|
Microsoft.Storage/storageAccounts/queueServices/queues/messages/* |
none | Microsoft.Storage/storageAccounts/queueServices/queues/messages/read Microsoft.Storage/storageAccounts/queueServices/queues/messages/write Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete Microsoft.Storage/storageAccounts/queueServices/queues/messages/add/action Microsoft.Storage/storageAccounts/queueServices/queues/messages/process/action |
Microsoft.Storage/storageAccounts/queueServices/queues/messages/* |
Microsoft.Storage/storageAccounts/queueServices/queues/messages/delete |
Microsoft.Storage/storageAccounts/queueServices/queues/messages/read Microsoft.Storage/storageAccounts/queueServices/queues/messages/write Microsoft.Storage/storageAccounts/queueServices/queues/messages/add/action Microsoft.Storage/storageAccounts/queueServices/queues/messages/process/action |
Σημείωση
If a user is assigned a role that excludes a data action in NotDataActions
, and is assigned a second role that grants access to the same data action, the user is allowed to perform that data action. NotDataActions
is not a deny rule – it is simply a convenient way to create a set of allowed data actions when specific data actions need to be excluded.
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:
Role is available for assignment | Example |
---|---|
One subscription | "/subscriptions/{subscriptionId1}" |
Two subscriptions | "/subscriptions/{subscriptionId1}", "/subscriptions/{subscriptionId2}" |
Network resource group | "/subscriptions/{subscriptionId1}/resourceGroups/Network" |
One management group | "/providers/Microsoft.Management/managementGroups/{groupId1}" |
Management group and a subscription | "/providers/Microsoft.Management/managementGroups/{groupId1}", "/subscriptions/{subscriptionId1}", |
All scopes (applies only to built-in roles) | "/" |
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 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.
Action string | Description |
---|---|
* |
Create and manage resources of all types. |
*/delete |
Delete resources of all types. |
*/write |
Write resources of all types. |
Microsoft.Authorization/denyAssignments/delete |
Delete a deny assignment at the specified scope. |
Microsoft.Authorization/denyAssignments/write |
Create a deny assignment at the specified scope. |
Microsoft.Authorization/roleAssignments/delete |
Delete a role assignment at the specified scope. |
Microsoft.Authorization/roleAssignments/write |
Create a role assignment at the specified scope. |
Microsoft.Authorization/roleDefinitions/delete |
Delete the specified custom role definition. |
Microsoft.Authorization/roleDefinitions/write |
Create or update a custom role definition with specified permissions and assignable scopes. |