Table of Contents
So Many Roles to Work With
A bunch of built-in Azure AD roles exist to help manage resources. Microsoft adds more to the list over time. Not all the roles exist in Microsoft 365 tenants, but you can expect to find at least twenty roles, including:
- Global administrator.
- Exchange administrator.
- SharePoint administrator.
- Teams administrator.
- Compliance administrator.
- Reports reader.
- User administrator.
- Helpdesk administrator.
These are Azure AD roles. Another set of compliance roles exist like “Fraud Investigators” and “Disposition Processors,” used to grant the ability to perform information governance and protection tasks. As explained in this post, the Exchange Online Get-RoleGroup cmdlet reveals both types, but for the purpose of this article, I focus on the assignable Azure AD roles.
Finding the List of Roles
In my tenant, there are 31 Azure AD roles in use. I know this because I ran the Get-MgDirectoryRole cmdlet. Here’s what I see (list trimmed for space):
[array]$DirectoryRoles = Get-MgDirectoryRole | Sort DisplayName $DirectoryRoles | Format-Table DisplayName, Id DisplayName Id ----------- -- Attack Simulation Administrator f28eae22-7444-492d-bb0a-d3e41f8f9d4f Attribute Assignment Administrator b1042b1d-c84a-448e-9ca8-e6ad85e4fb65 Attribute Definition Administrator 327df668-5ea8-4ad8-b153-75d326b3c7d1 Azure AD Joined Device Local Administrator 268030c9-556f-47a6-a167-5970cb734558 Billing Administrator 07308ce7-381b-4fb1-b31e-398b8a66c946 Compliance Administrator 88b6939a-ef4b-4e8e-9aba-00f4f8447e66 Compliance Data Administrator fdc30bad-3a16-4c24-ac89-79b73ad9468d Customer LockBox Access Approver 1402c923-f478-4a9c-82b1-0511726c43bd
This is functionally equivalent to running the Get-AzureADDirectoryRole cmdlet from the soon-to-deprecated Azure AD module. Other Azure AD administrative roles exist but haven’t been used. You can see these roles by running the Get-MgDirectoryRoleTemplate cmdlet.
The role identifier is the important piece of information because we need this to assign a role to a user account. To store the role identifier in a variable to make it easier to use, we filter it from the set of roles. For instance, these commands return the role identifier for the Global administrator and Teams administrator roles:
$GlobalAdminRoleId = $DirectoryRoles | ? {$_.DisplayName -eq "Global administrator"} | Select -ExpandProperty Id $TeamsAdminRoleId = $DirectoryRoles | ? {$_.DisplayName -eq "Teams administrator"} | Select -ExpandProperty Id
Assigning Azure AD Roles to User Accounts
The New-MgDirectoryRoleMemberByRef cmdlet assign an Azure AD role to a user account. This cmdlet works like the New-MgGroupOwnerByRef cmdlet used to assign a new user to an Azure AD group (see this post about group management with the Microsoft Graph PowerShell SDK).
In this example, we first fetch the identifier for a user account and the set of current holders of the role. We then check the user identifier against the set of current role holders and if the account is not in the list, we assign the role using New-MgDirectoryRoleByRef:
$User = Get-MgUser -UserId Ken.Bowers@Office365itpros.com $RoleMembers = Get-MgDirectoryRoleMember -DirectoryRoleId $TeamsAdminRoleId If ($User.Id -notin $RoleMembers.Id) { Write-Host ("Adding user {0} to the Teams administrator role" -f $User.DisplayName) New-MgDirectoryRoleMemberByRef -DirectoryRoleId $TeamsAdminRoleId -BodyParameter @{"@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/$($user.Id)"} }
By comparison, the equivalent Azure AD cmdlet is simpler:
Add-AzureADDirectoryRoleMember -ObjectId $TeamsAdminRoleId -RefObjectId $User.Id
To check that the correct account was added to the Azure AD role, fetch the set of updated role members and loop through the set to retrieve the display name of each role holder:
$RoleMembers = Get-MgDirectoryRoleMember -DirectoryRoleId $TeamsAdminRoleId ForEach ($RoleMember in $RoleMembers) { Write-Host $RoleMember.AdditionalProperties["displayName"]}
Alternatively, check the assignments through Azure AD admin center (Figure 1):

There doesn’t appear to be a cmdlet available currently to remove a role assignment comparable to the Remove-AzureADDirectoryRoleMember cmdlet. This might be because Microsoft hasn’t yet added such a cmdlet to the SDK. Until they do, run the Azure AD cmdlet or use a graph API query to remove role assignments – or remove the assignments from the Azure AD admin center.
More Learning Required
Like many topics related to the Microsoft Graph PowerShell SDK, some more work is required to fully understand the intricacies of role assignment management, especially in deleting assignments. The good news is that this area is under active development. We can but wait for progress.
Insight like this doesn’t come easily. You’ve got to know the technology and understand how to look behind the scenes. Benefit from the knowledge and experience of the Office 365 for IT Pros team by subscribing to the best eBook covering Office 365 and the wider Microsoft 365 ecosystem.