Assign Azure AD Roles to User Accounts with the Microsoft Graph PowerShell SDK

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.