Use roles to control resource access

Built-in roles for Azure Resources (uses PowerShell)

Azure provides several built-in roles to cover the most common security scenarios. To understand how the roles work, let's examine three roles that apply to all resource types:

• Owner: Has full access to all resources, including the right to delegate access to others.
• Contributor: Can create and manage all types of Azure resources, but can’t grant access to others.
• Reader: Can view existing Azure resources.

Role definitions

Each role is a set of properties defined in a JavaScript Object Notation (JSON) file. This role definition includes a Name, ID, and Description. It also includes the allowable permissions (Actions), denied permissions (NotActions), and scope (for example, read access) for the role.

For the Owner role, that means all actions, indicated by an asterisk (*); no denied actions; and all scopes, indicated by a forward slash (/).

You can get this information using the PowerShell Get-AzRoleDefinition Owner cmdlet.

Get-AzRoleDefinition Owner

This code should produce the following output:

Name             : Owner
Id               : 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
IsCustom         : False
Description      : Lets you manage everything, including access to resources.
Actions          : {*}
NotActions       : {}
DataActions      : {}
NotDataActions   : {}
AssignableScopes : {/}

Try the same for the Contributor and Reader roles to see the actions allowed and denied.

Built-in roles

For an in-depth examination of the RBAC and user roles in Microsoft Entra ID, see Examine RBAC and user roles in Microsoft Entra ID.

What's a role definition?

A role definition is a collection of permissions. A role definition lists the operations the role can perform, such as read, write, and delete. It can also list the operations that can't be performed or operations related to underlying data.

As previously described, a role definition has the following structure:

This structure is represented as JSON when used in role-based access control (RBAC) or from the underlying API. For example, here's the Contributor role definition in JSON format.

{
  "Name": "Contributor",
  "Id": "b24988ac-6180-42a0-ab88-20f7382dd24c",
  "IsCustom": false,
  "Description": "Lets you manage everything except access to resources.",
  "Actions": [
    "*"
  ],
  "NotActions": [
    "Microsoft.Authorization/*/Delete",
    "Microsoft.Authorization/*/Write",
    "Microsoft.Authorization/elevateAccess/Action"
  ],
  "DataActions": [],
  "NotDataActions": [],
  "AssignableScopes": [
    "/"
  ]
}

Actions and NotActions

You can tailor the Actions and NotActions properties to grant and deny the exact permissions you need. These properties are always in the format: {Company}.{ProviderName}/{resourceType}/{action}.

As an example, here are the actions for the three roles we looked at previously:

The wildcard (*) operation under Actions indicates that the principal assigned to this role can perform all actions; or in other words, this role can manage everything, including actions defined in the future as new resource types are added to Azure. With the Reader role, only the read action is allowed.

The operations under NotActions are subtracted from Actions. With the Contributor role, NotActions removes this role's ability to manage access to resources, and also removes assigning access to resources.

DataActions and NotDataActions

Data operations are specified in the DataActions and NotDataActions properties. You can specify data operations separately from the management operations. This prevents current role assignments with wildcards (*) from suddenly having access to data. Here are some data operations that you can specify 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

You can only add data operations to the DataActions and NotDataActions properties. Resource providers identify which operations are data operations by setting the isDataAction property to true. Roles that don't have data operations can omit these properties from the role definition.

These actions work exactly like their management cousins. You can specify the actions you want to allow (or * for all), then provide a list of specific actions to remove in the NotDataActions collection. Here are some examples; you can find the full list of actions and data actions in the resource provider documentation:

Assignable Scopes

Defining the Actions and NotActions properties is not enough to fully implement a role. You also need to properly scope your role.

The AssignableScopes property of the role specifies the scopes (subscriptions, resource groups, or resources) within which the role is available for assignment. You can make the custom role available for assignment just in the subscriptions or resource groups that need it, thus avoiding cluttering the user experience for the rest of the subscriptions or resource groups.

Here are some examples:

Create roles

Microsoft Entra ID comes with built-in roles that are likely to cover 99% of what you'll ever want to do. It's preferable to use a built-in role if possible. However, you can create custom roles if you find it necessary.

You can create a new role through several mechanisms:

• Microsoft Entra admin center: You can use the Microsoft Entra admin center to create a custom role by selecting Roles & admins under Roles & admins in the left menu, then selecting New custom role.

• Azure portal: You can use the Azure portal to create a custom role by selecting Microsoft Entra ID > Roles and administrators > New custom role.

• Azure PowerShell: You can use the New-AzRoleDefinition cmdlet to define a new role.

• Azure Graph API: You can use a REST call to the Graph API to programmatically create a new role.

This module's Summary section includes a link to the documentation for these approaches.