Assign Azure AD roles at different scopes

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

  1. Sign in to the Azure portal or Azure AD admin center.

  2. Select Azure Active Directory > Roles and administrators to see the list of all available roles.

    Roles and administrators page in Azure Active Directory.

  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 Azure AD roles using PowerShell.

  1. 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
    
  2. In a PowerShell window, use Connect-AzureAD to sign in to your tenant.

    Connect-AzureAD
    
  3. Use Get-AzureADUser to get the user.

    $user = Get-AzureADUser -Filter "userPrincipalName eq 'alice@contoso.com'"
    
  4. Use Get-AzureADMSRoleDefinition to get the role you want to assign.

    $roleDefinition = Get-AzureADMSRoleDefinition -Filter "displayName eq 'Billing Administrator'"
    
  5. Set tenant as scope of role assignment.

    $directoryScope = '/'
    
  6. 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.

  1. Sign in to the Graph Explorer.

  2. Use List user API to get the user.

    GET https://graph.microsoft.com/beta/users?$filter=userPrincipalName eq 'alice@contoso.com'
    
  3. Use the List roleDefinitions API to get the role you want to assign.

    GET https://graph.microsoft.com/beta/rolemanagement/directory/roleDefinitions?$filter=displayName eq 'Billing Administrator'
    
  4. Use the Create roleAssignments API to assign the role.\

    POST https://graph.microsoft.com/beta/roleManagement/directory/roleAssignments
    {
        "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

  1. Sign in to the Azure portal or Azure AD admin center.

  2. Select Azure Active Directory > Administrative units to see the list of all administrative units.

  3. Select an administrative unit.

    Administrative Units in Azure Active Directory.

  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 Azure Active Directory.

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

  1. 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
    
  2. In a PowerShell window, use Connect-AzureAD to sign in to your tenant.

    Connect-AzureAD
    
  3. Use Get-AzureADUser to get the user.

    $user = Get-AzureADUser -Filter "userPrincipalName eq 'alice@contoso.com'"
    
  4. Use Get-AzureADMSRoleDefinition to get the role you want to assign.

    $roleDefinition = Get-AzureADMSRoleDefinition -Filter "displayName eq 'User Administrator'"
    
  5. 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
    
  6. 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.

  1. Sign in to the Graph Explorer.

  2. Use List user API to get the user.

    GET https://graph.microsoft.com/beta/users?$filter=userPrincipalName eq 'alice@contoso.com'
    
  3. Use the List roleDefinitions API to get the role you want to assign.

    GET https://graph.microsoft.com/beta/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/beta/administrativeUnits?$filter=displayName eq 'Seattle Admin Unit'
    
  5. Use the Create roleAssignments API to assign the role.

    POST https://graph.microsoft.com/beta/roleManagement/directory/roleAssignments
    {
        "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.

Assign roles scoped to an app registration

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

Azure portal

  1. Sign in to the Azure portal or Azure AD admin center.

  2. Select Azure Active Directory > App registrations to see the list of all app registrations.

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

    App registrations in Azure Active Directory.

  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 Azure Active Directory.

  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 Azure Active Directory.

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

    Successfully added role assignment scoped to an app registrations in Azure Active Directory.

    Role assigned to the user scoped to an app registrations in 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 managing app registrations only.

PowerShell

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

  1. 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
    
  2. In a PowerShell window, use Connect-AzureAD to sign in to your tenant.

    Connect-AzureAD
    
  3. Use Get-AzureADUser to get the user.

    $user = Get-AzureADUser -Filter "userPrincipalName eq 'alice@contoso.com'"
    
  4. Use Get-AzureADMSRoleDefinition to get the role you want to assign.

    $roleDefinition = Get-AzureADMSRoleDefinition -Filter "displayName eq 'Application Administrator'"
    
  5. 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
    
  6. 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.

  1. Sign in to the Graph Explorer.

  2. Use List user API to get the user.

    GET https://graph.microsoft.com/beta/users?$filter=userPrincipalName eq 'alice@contoso.com'
    
  3. Use the List roleDefinitions API to get the role you want to assign.

    GET https://graph.microsoft.com/beta/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/beta/applications?$filter=displayName eq 'f/128 Filter Photos'
    
  5. Use the Create roleAssignments API to assign the role.

    POST https://graph.microsoft.com/beta/roleManagement/directory/roleAssignments
    {
        "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.

Next steps