Rediger

Assign Microsoft Entra roles at different scopes

  • Artikkel

In Microsoft Entra ID, you typically assign Microsoft Entra roles so that they apply to the entire tenant. However, you can also assign Microsoft Entra roles for different resources, such as administrative units or application registrations. For example, you could assign the Helpdesk Administrator role so that it just applies to a particular administrative unit and not the entire tenant. The resources that a role assignment applies to is also called the scope. This article describes how to assign Microsoft Entra roles at tenant, administrative unit, and application registration scopes. For more information about scope, see Overview of role-based access control (RBAC) in Microsoft Entra ID.

Prerequisites

  • Privileged Role Administrator or Global Administrator.
  • Microsoft Graph PowerShell SDK installed when using PowerShell.
  • Admin consent when using Graph Explorer for Microsoft Graph API.

For more information, see Prerequisites to use PowerShell or Graph Explorer.

Assign roles scoped to the tenant

This section describes how to assign roles at the tenant scope.

Microsoft Entra admin center

Tip

Steps in this article might vary slightly based on the portal you start from.

  1. Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.

  2. Browse to Identity > Roles & admins > Roles & admins.

    Roles and administrators page in Microsoft Entra ID.

  3. Select a role to see its assignments. To help you find the role you need, use Add filters to filter the roles.

  4. Select Add assignments and then select the users you want to assign to this role.

    Add assignments pane for selected role.

  5. Select Add to assign the role.

PowerShell

Follow these steps to assign Microsoft Entra roles using PowerShell.

  1. Open a PowerShell window. If necessary, use Install-Module to install Microsoft Graph PowerShell. For more information, see Prerequisites to use PowerShell or Graph Explorer.

    Install-Module Microsoft.Graph -Scope CurrentUser

  2. In a PowerShell window, use Connect-MgGraph to sign in to your tenant.

    Connect-MgGraph -Scopes "RoleManagement.Read.Directory","User.Read.All","RoleManagement.ReadWrite.Directory"

  3. Use Get-MgUser to get the user.

    $user = Get-MgUser -Filter "userPrincipalName eq 'alice@contoso.com'"

  4. Use Get-MgRoleManagementDirectoryRoleDefinition to get the role you want to assign.

    $roleDefinition = Get-MgRoleManagementDirectoryRoleDefinition -Filter "displayName eq 'Billing Administrator'"

  5. Set tenant as scope of role assignment.

    $directoryScope = '/'

  6. Use New-MgRoleManagementDirectoryRoleAssignment to assign the role.

    $roleAssignment = New-MgRoleManagementDirectoryRoleAssignment `
   -DirectoryScopeId $directoryScope -PrincipalId $user.Id `
   -RoleDefinitionId $roleDefinition.Id

Microsoft Graph API

Follow these instructions to assign a role using the Microsoft Graph API in Graph Explorer.

  1. Sign in to the Graph Explorer.

  2. Use List users API to get the user.

    GET https://graph.microsoft.com/v1.0/users?$filter=userPrincipalName eq 'alice@contoso.com'

  3. Use the List unifiedRoleDefinitions API to get the role you want to assign.

    GET https://graph.microsoft.com/v1.0/rolemanagement/directory/roleDefinitions?$filter=displayName eq 'Billing Administrator'

  4. Use the Create unifiedRoleAssignment API to assign the role.

    POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments
{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "<provide objectId of the user obtained above>",
    "roleDefinitionId": "<provide templateId of the role obtained above>",
    "directoryScopeId": "/"
}

Assign roles scoped to an administrative unit

This section describes how to assign roles at an administrative unit scope.

Microsoft Entra admin center

  1. Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.

  2. Browse to Identity > Roles & admins > Admin units.

  3. Select an administrative unit.

    Administrative Units in Microsoft Entra ID.

  4. Select Roles and administrators from the left nav menu to see the list of all roles available to be assigned over an administrative unit.

    Roles and administrators menu under administrative Units in Microsoft Entra ID.

  5. Select the desired role.

  6. Select Add assignments and then select the users or group you want to assign this role to.

  7. Select Add to assign the role scoped over the administrative unit.

Note

You will not see the entire list of Microsoft Entra built-in or custom roles here. This is expected. We show the roles which have permissions related to the objects that are supported within the administrative unit. To see the list of objects supported within an administrative unit, see Administrative units in Microsoft Entra ID.

PowerShell

Follow these steps to assign Microsoft Entra roles at administrative unit scope using PowerShell.

  1. Open a PowerShell window. If necessary, use Install-Module to install Microsoft Graph PowerShell. For more information, see Prerequisites to use PowerShell or Graph Explorer.

    Install-Module Microsoft.Graph -Scope CurrentUser

  2. In a PowerShell window, use Connect-MgGraph to sign in to your tenant.

    Connect-MgGraph -Scopes "Directory.Read.All","RoleManagement.Read.Directory","User.Read.All","RoleManagement.ReadWrite.Directory"

  3. Use Get-MgUser to get the user.

    $user = Get-MgUser -Filter "userPrincipalName eq 'alice@contoso.com'"

  4. Use Get-MgRoleManagementDirectoryRoleDefinition to get the role you want to assign.

    $roleDefinition = Get-MgRoleManagementDirectoryRoleDefinition `
   -Filter "displayName eq 'User Administrator'"

  5. Use Get-MgDirectoryAdministrativeUnit to get the administrative unit you want the role assignment to be scoped to.

    $adminUnit = Get-MgDirectoryAdministrativeUnit -Filter "displayName eq 'Seattle Admin Unit'"
$directoryScope = '/administrativeUnits/' + $adminUnit.Id

  6. Use New-MgRoleManagementDirectoryRoleAssignment to assign the role.

    $roleAssignment = New-MgRoleManagementDirectoryRoleAssignment `
   -DirectoryScopeId $directoryScope -PrincipalId $user.Id `
   -RoleDefinitionId $roleDefinition.Id

Microsoft Graph API

Follow these instructions to assign a role at administrative unit scope using the Microsoft Graph API in Graph Explorer.

  1. Sign in to the Graph Explorer.

  2. Use List users API to get the user.

    GET https://graph.microsoft.com/v1.0/users?$filter=userPrincipalName eq 'alice@contoso.com'

  3. Use the List unifiedRoleDefinitions API to get the role you want to assign.

    GET https://graph.microsoft.com/v1.0/rolemanagement/directory/roleDefinitions?$filter=displayName eq 'User Administrator'

  4. Use the List administrativeUnits API to get the administrative unit you want the role assignment to be scoped to.

    GET https://graph.microsoft.com/v1.0/directory/administrativeUnits?$filter=displayName eq 'Seattle Admin Unit'

  5. Use the Create unifiedRoleAssignment API to assign the role.

    POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments
{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "<provide objectId of the user obtained above>",
    "roleDefinitionId": "<provide templateId of the role obtained above>",
    "directoryScopeId": "/administrativeUnits/<provide objectId of the admin unit obtained above>"
}

Note

Here directoryScopeId is specified as /administrativeUnits/foo, instead of /foo. It is by design. The scope /administrativeUnits/foo means the principal can manage the members of the administrative unit (based on the role that she is assigned), not the administrative unit itself. The scope of /foo means the principal can manage that Microsoft Entra object itself. In the subsequent section, you will see that the scope is /foo because a role scoped over an app registration grants the privilege to manage the object itself.

Assign roles scoped to an app registration

This section describes how to assign roles at an application registration scope.

Microsoft Entra admin center

  1. Sign in to the Microsoft Entra admin center as at least a Privileged Role Administrator.

  2. Browse to Identity > Applications > App registrations.

  3. Select an application. You can use search box to find the desired app.

    App registrations in Microsoft Entra ID.

  4. Select Roles and administrators from the left nav menu to see the list of all roles available to be assigned over the app registration.

    Roles for an app registrations in Microsoft Entra ID.

  5. Select the desired role.

  6. Select Add assignments and then select the users or group you want to assign this role to.

    Add role assignment scoped to an app registrations in Microsoft Entra ID.

  7. Select Add to assign the role scoped over the app registration.

    Successfully added role assignment scoped to an app registrations in Microsoft Entra ID.

    Role assigned to the user scoped to an app registrations in Microsoft Entra ID.

Note

You will not see the entire list of Microsoft Entra built-in or custom roles here. This is expected. We show the roles which have permissions related to managing app registrations only.

PowerShell

Follow these steps to assign Microsoft Entra roles at application scope using PowerShell.

  1. Open a PowerShell window. If necessary, use Install-Module to install Microsoft Graph PowerShell. For more information, see Prerequisites to use PowerShell or Graph Explorer.

    Install-Module Microsoft.Graph -Scope CurrentUser

  2. In a PowerShell window, use Connect-MgGraph to sign in to your tenant.

    Connect-MgGraph -Scopes "Application.Read.All","RoleManagement.Read.Directory","User.Read.All","RoleManagement.ReadWrite.Directory"

  3. Use Get-MgUser to get the user.

    $user = Get-MgUser -Filter "userPrincipalName eq 'alice@contoso.com'"

  4. Use Get-MgRoleManagementDirectoryRoleDefinition to get the role you want to assign.

    $roleDefinition = Get-MgRoleManagementDirectoryRoleDefinition `
   -Filter "displayName eq 'Application Administrator'"

  5. Use Get-MgApplication to get the app registration you want the role assignment to be scoped to.

    $appRegistration = Get-MgApplication -Filter "displayName eq 'f/128 Filter Photos'"
$directoryScope = '/' + $appRegistration.Id

  6. Use New-MgRoleManagementDirectoryRoleAssignment to assign the role.

    $roleAssignment = New-MgRoleManagementDirectoryRoleAssignment `
   -DirectoryScopeId $directoryScope -PrincipalId $user.Id `
   -RoleDefinitionId $roleDefinition.Id

Microsoft Graph API

Follow these instructions to assign a role at application scope using the Microsoft Graph API in Graph Explorer.

  1. Sign in to the Graph Explorer.

  2. Use List users API to get the user.

    GET https://graph.microsoft.com/v1.0/users?$filter=userPrincipalName eq 'alice@contoso.com'

  3. Use the List unifiedRoleDefinitions API to get the role you want to assign.

    GET https://graph.microsoft.com/v1.0/rolemanagement/directory/roleDefinitions?$filter=displayName eq 'Application Administrator'

  4. Use the List applications API to get the administrative unit you want the role assignment to be scoped to.

    GET https://graph.microsoft.com/v1.0/applications?$filter=displayName eq 'f/128 Filter Photos'

  5. Use the Create unifiedRoleAssignment API to assign the role.

    POST https://graph.microsoft.com/v1.0/roleManagement/directory/roleAssignments

{
    "@odata.type": "#microsoft.graph.unifiedRoleAssignment",
    "principalId": "<provide objectId of the user obtained above>",
    "roleDefinitionId": "<provide templateId of the role obtained above>",
    "directoryScopeId": "/<provide objectId of the app registration obtained above>"
}

Note

Here directoryScopeId is specified as /foo, unlike the section above. It is by design. The scope of /foo means the principal can manage that Microsoft Entra object. The scope /administrativeUnits/foo means the principal can manage the members of the administrative unit (based on the role that she is assigned), not the administrative unit itself.

Next steps