Introduction
Microsoft Entra roles allow you to grant granular permissions to your admins, abiding by the principle of least privilege. Microsoft Entra roles control access to Microsoft Entra resources such as users, groups, and applications using the Microsoft Graph API.
A scope is a way to limit the permitted actions to a particular set of resources as part of a role assignment.
When you assign a role, you specify one of the following types of scope:
- tenant
- administrative unit
- application registration
- enterprise application (service principal)
- user
- group
The type of scope that can be defined for a role during role assignment is affected by role permissions included in the role.
Create a role assignment
When creating a role assignment, you can specify the scope in the directoryScopeId property of the request body. The value of this property should be the ID of the scope you want to assign the role to.
POST /v1.0/roleManagement/directory/roleAssignments
{
"principalId": "user-or-group-or-application-id",
"roleDefinitionId": "role-definition-id",
"directoryScopeId": "scope-id"
}
Based on the type of scope, the directoryScopeId should be formatted as follows:
- tenant:
directoryScopeId: "/" - administrative unit:
directoryScopeId: "/administrativeUnits/{administrative_unit_id}" - application:
directoryScopeId: "/{application_object_id}" - service principal:
directoryScopeId: "/{service_principal_id}" - user:
directoryScopeId: "/{user_id}" - group:
directoryScopeId: "/{group_id}"
As you can see, the directoryScopeId has the same format when the scope is limited to an application, a service principal, a user, or a group. The Graph API can recognize the type from the entity id.
