Overview of role-based access control in Azure Active Directory

This article describes how to understand Azure Active Directory (Azure AD) role-based access control. Azure AD roles allow you to grant granular permissions to your admins, abiding by the principle of least privilege. Azure AD built-in and custom roles operate on concepts similar to those you will find in the role-based access control system for Azure resources (Azure roles). The difference between these two role-based access control systems is:

  • Azure AD roles control access to Azure AD resources such as users, groups, and applications using Graph API
  • Azure roles control access to Azure resources such as virtual machines or storage using Azure Resource Management

Both systems contain similarly used role definitions and role assignments. However, Azure AD role permissions can't be used in Azure custom roles and vice versa.

Understand Azure AD role-based access control

Azure AD supports 2 types of roles definitions -

Built-in roles are out of box roles that have a fixed set of permissions. These role definitions cannot be modified. There are many built-in roles that Azure AD supports, and the list is growing. To round off the edges and meet your sophisticated requirements, Azure AD also supports custom roles. Granting permission using custom Azure AD roles is a two-step process that involves creating a custom role definition and then assigning it using a role assignment. A custom role definition is a collection of permissions that you add from a preset list. These permissions are the same permissions used in the built-in roles.

Once you’ve created your custom role definition (or using a built-in role), you can assign it to a user by creating a role assignment. A role assignment grants the user the permissions in a role definition at a specified scope. This two-step process allows you to create a single role definition and assign it many times at different scopes. A scope defines the set of Azure AD resources the role member has access to. The most common scope is organization-wide (org-wide) scope. A custom role can be assigned at org-wide scope, meaning the role member has the role permissions over all resources in the organization. A custom role can also be assigned at an object scope. An example of an object scope would be a single application. The same role can be assigned to one user over all applications in the organization and then to another user with a scope of only the Contoso Expense Reports app.

Azure AD built-in and custom roles operate on concepts similar to Azure role-based access control (Azure RBAC). The difference between these two role-based access control systems is that Azure RBAC controls access to Azure resources such as virtual machines or storage using Azure Resource Management, and Azure AD custom roles control access to Azure AD resources using Graph API. Both systems leverage the concept of role definitions and role assignments. Azure AD RBAC permissions cannot be included in Azure roles and vice versa.

How Azure AD determines if a user has access to a resource

The following are the high-level steps that Azure AD uses to determine if you have access to a management resource. Use this information to troubleshoot access issues.

  1. A user (or service principal) acquires a token to the Microsoft Graph or Azure AD Graph endpoint.
  2. The user makes an API call to Azure Active Directory (Azure AD) via Microsoft Graph or Azure AD Graph using the issued token.
  3. Depending on the circumstance, Azure AD takes one of the following actions:
    • Evaluates the user’s role memberships based on the wids claim in the user’s access token.
    • Retrieves all the role assignments that apply for the user, either directly or via group membership, to the resource on which the action is being taken.
  4. Azure AD determines if the action in the API call is included in the roles the user has for this resource.
  5. If the user doesn't have a role with the action at the requested scope, access is not granted. Otherwise access is granted.

Role assignment

A role assignment is an Azure AD resource that attaches a role definition to a user at a particular scope to grant access to Azure AD resources. Access is granted by creating a role assignment, and access is revoked by removing a role assignment. At its core, a role assignment consists of three elements:

  • Azure AD user
  • Role definition
  • Resource scope

You can create role assignments using the Azure portal, Azure AD PowerShell, or Graph API. You can also view the assignments for a custom role.

The following diagram shows an example of a role assignment. In this example, Chris Green has been assigned the App registration administrator custom role at the scope of the Contoso Widget Builder app registration. The assignment grants Chris the permissions of the App registration administrator role for only this specific app registration.

Role assignment is how permissions are enforced and has three parts

Security principal

A security principal represents the user that is to be assigned access to Azure AD resources. A user is an individual who has a user profile in Azure Active Directory.


A role definition, or role, is a collection of permissions. A role definition lists the operations that can be performed on Azure AD resources, such as create, read, update, and delete. There are two types of roles in Azure AD:

  • Built-in roles created by Microsoft that can't be changed.
  • Custom roles created and managed by your organization.


A scope is the restriction of permitted actions to a particular Azure AD resource as part of a role assignment. When you assign a role, you can specify a scope that limits the administrator's access to a specific resource. For example, if you want to grant a developer a custom role, but only to manage a specific application registration, you can include the specific application registration as a scope in the role assignment.

Required license plan

Using built-in roles in Azure AD is free, while custom roles requires an Azure AD Premium P1 license. To find the right license for your requirements, see Comparing generally available features of the Free, Basic, and Premium editions.

Next steps