Custom Azure RBAC roles: actions, notActions, dataActions and assignable scopes

When no built-in role fits, you can create a custom Azure RBAC role. A custom role is a JSON role definition that lists exactly which operations are allowed. You create it in the portal (clone an existing role and edit it), with Azure PowerShell (New-AzRoleDefinition) or with the Azure CLI (az role definition create --role-definition role.json). Custom roles are stored in the Microsoft Entra tenant and can be shared across the subscriptions listed in their assignable scopes.

Operations are written as resource provider strings, for example Microsoft.Compute/virtualMachines/start/action or Microsoft.Storage/storageAccounts/read. Wildcards are allowed: Microsoft.Compute/virtualMachines/* means every operation on VMs. The Actions property lists control-plane (management) operations that go through Azure Resource Manager: create, read, update, delete and special actions such as restart. The NotActions property subtracts operations from a wildcard in Actions. For instance, Actions: ["*"] with NotActions: ["Microsoft.Authorization/*/Delete", "Microsoft.Authorization/*/Write"] is essentially how Contributor is defined.

Important: NotActions is not a deny. It only removes operations from this role's grant. If the same user also has another role that allows the excluded operation, they can still perform it. To actually block something you rely on the absence of permissions, Azure Policy, resource locks or system-created deny assignments.

Data-plane operations act on the data inside a resource, such as reading a blob or a queue message, and are listed in DataActions and NotDataActions. For example, Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read is a data action. This split is why Contributor on a storage account can manage the account but cannot read blobs through Entra ID authorization; that needs a data role such as Storage Blob Data Reader. Only services that support Entra data-plane authorization (Storage, Key Vault with RBAC, Service Bus, Event Hubs and others) have data actions.

AssignableScopes lists where the custom role can be assigned: one or more management groups, subscriptions or resource groups. A role scoped to a subscription can be assigned at that subscription or anything below it. Custom roles that include DataActions cannot list a management group in their assignable scopes, and there are tenant-wide limits on how many custom roles you can create, so keep them few and reusable. Creating or updating a custom role requires Microsoft.Authorization/roleDefinitions/write, which Owner and User Access Administrator have.

A good workflow is: find the closest built-in role, export it with az role definition list --name "Virtual Machine Contributor", edit the JSON, give it a clear name and description, set assignable scopes as narrow as possible, and test it with a test user and Check access before rolling it out.

Key terms

Actions

Control-plane operations the role allows, such as creating or restarting a VM.

NotActions

Operations removed from the Actions wildcard for this role only; not a deny if another role grants them.

DataActions

Data-plane operations the role allows, such as reading blobs or Key Vault secrets.

AssignableScopes

The management groups, subscriptions or resource groups where a custom role may be assigned.

Check yourself