Assign Azure AD roles at different scopes - Azure Active Directory

Article
08/21/2022
6 minutes to read

In Azure Active Directory (Azure AD), you typically assign Azure AD roles so that they apply to the entire tenant. However, you can also assign Azure AD 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 call the scope. This article describes how to assign Azure AD roles at tenant, administrative unit, and application registration scopes. For more information about scope, see Overview of RBAC in Azure AD.

Prerequisites

Privileged Role Administrator or Global Administrator.
AzureADPreview module 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.

Azure portal

Sign in to the Azure portal or Azure AD admin center.
Select Azure Active Directory > Roles and administrators to see the list of all available roles.
Select a role to see its assignments. To help you find the role you need, use Add filters to filter the roles.
Select Add assignments and then select the users you want to assign to this role.
Select Add to assign the role.

PowerShell

Follow these steps to assign Azure AD roles using PowerShell.

Open a PowerShell window and use Import-Module to import the AzureADPreview module. For more information, see Prerequisites to use PowerShell or Graph Explorer.
```
Import-Module -Name AzureADPreview -Force
```
In a PowerShell window, use Connect-AzureAD to sign in to your tenant.
```
Connect-AzureAD
```

Use Get-AzureADUser to get the user.

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

Use Get-AzureADMSRoleDefinition to get the role you want to assign.
(Video) Azure Active Directory (AD, AAD) Tutorial | Identity and Access Management Service
```
$roleDefinition = Get-AzureADMSRoleDefinition -Filter "displayName eq 'Billing Administrator'"
```
Set tenant as scope of role assignment.
```
$directoryScope = '/'
```

Use New-AzureADMSRoleAssignment to assign the role.

$roleAssignment = New-AzureADMSRoleAssignment -DirectoryScopeId $directoryScope -RoleDefinitionId $roleDefinition.Id -PrincipalId $user.objectId

Microsoft Graph API

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

Sign in to the Graph Explorer.
See Also
Create or update Azure custom roles using the Azure portal - Azure RBAC What's the difference between Azure roles and Azure AD roles?

Use List users API to get the user.

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

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'

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.

Azure portal

Sign in to the Azure portal or Azure AD admin center.
Select Azure Active Directory > Administrative units to see the list of all administrative units.
Select an administrative unit.
Select Roles and administrators from the left nav menu to see the list of all roles available to be assigned over an administrative unit.
Select the desired role.
Select Add assignments and then select the users or group you want to assign this role to.
Select Add to assign the role scoped over the administrative unit.
(Video) Create a new user in Azure active Directory ||assign roles|| remove a role||Azure Active Directory

Note

You will not see the entire list of Azure AD 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. Refer to this documentation to see the list of objects supported within an administrative unit.

PowerShell

Follow these steps to assign Azure AD roles at administrative unit scope using PowerShell.

Open a PowerShell window and use Import-Module to import the AzureADPreview module. For more information, see Prerequisites to use PowerShell or Graph Explorer.
```
Import-Module -Name AzureADPreview -Force
```
In a PowerShell window, use Connect-AzureAD to sign in to your tenant.
```
Connect-AzureAD
```

Use Get-AzureADUser to get the user.

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

Use Get-AzureADMSRoleDefinition to get the role you want to assign.

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

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

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

Use New-AzureADMSRoleAssignment to assign the role.

$roleAssignment = New-AzureADMSRoleAssignment -DirectoryScopeId $directoryScope -RoleDefinitionId $roleDefinition.Id -PrincipalId $user.objectId

Microsoft Graph API

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

Use List users API to get the user.

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

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'

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'
```

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 Azure AD 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.

(Video) Microsoft Entra - Permission Management

Assign roles scoped to an app registration

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

Azure portal

Sign in to the Azure portal or Azure AD admin center.
Select Azure Active Directory > App registrations to see the list of all app registrations.
Select an application. You can use search box to find the desired app.
Select Roles and administrators from the left nav menu to see the list of all roles available to be assigned over the app registration.
Select the desired role.
Select Add assignments and then select the users or group you want to assign this role to.
Select Add to assign the role scoped over the app registration.

Note

(Video) Azure AD Roles & administrators | Built-in Roles #PIM Eligible Vs Active assignments #infotechie365

You will not see the entire list of Azure AD 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 Azure AD roles at application scope using PowerShell.

Open a PowerShell window and use Import-Module to import the AzureADPreview module. For more information, see Prerequisites to use PowerShell or Graph Explorer.
```
Import-Module -Name AzureADPreview -Force
```
In a PowerShell window, use Connect-AzureAD to sign in to your tenant.
```
Connect-AzureAD
```

Use Get-AzureADUser to get the user.

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

Use Get-AzureADMSRoleDefinition to get the role you want to assign.

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

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

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

Use New-AzureADMSRoleAssignment to assign the role.

$roleAssignment = New-AzureADMSRoleAssignment -DirectoryScopeId $directoryScope -RoleDefinitionId $roleDefinition.Id -PrincipalId $user.objectId

Microsoft Graph API

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

Use List users API to get the user.

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

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'

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'
```

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 Azure AD 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.

(Video) Looking at Entra Permissions Management to Manage Permissions Across AWS, GCP and Azure

Next steps

List Azure AD role assignments.
Assign Azure AD roles to users.
Assign Azure AD roles to groups

Assign Azure AD roles at different scopes - Azure Active Directory - Microsoft Entra (2023)

Prerequisites

Assign roles scoped to the tenant

Azure portal

PowerShell

Microsoft Graph API

Assign roles scoped to an administrative unit

Azure portal

PowerShell

Microsoft Graph API

Assign roles scoped to an app registration

Azure portal

PowerShell

Microsoft Graph API

Next steps

Videos