How to Use Get-MgDirectoryRole to Fetch Microsoft 365 Directory Roles?

Microsoft 365 offers several directory roles that define what users can and cannot do in your tenant. Whether you're managing Global Administrators, Exchange Admins, or custom roles, it's essential to have visibility into these assignments. Fortunately, the Get-MgDirectoryRole cmdlet in Microsoft Graph PowerShell makes this process easy.

In this article, we'll explore what the cmdlet does, why it's useful, and how to use it with practical examples.

What is Get-MgDirectoryRole?

The Get-MgDirectoryRole cmdlet retrieves the directory roles that are currently activated in your Microsoft 365 tenant. This includes built-in roles like Global Administrator, User Administrator, Teams Administrator, and more.

Note: Only activated roles will appear—roles are "activated" when at least one user is assigned to them.

Why Use Get-MgDirectoryRole?

You may want to use Get-MgDirectoryRole for several reasons:

• Audit who has elevated privileges in your tenant
• Ensure no critical roles are left unassigned
• Verify least privilege access by checking role assignments
• Report on admin roles for compliance reviews

Combined with Get-MgDirectoryRoleMember, this cmdlet forms the foundation for Microsoft 365 role audits.

Cmdlet Syntax

Get-MgDirectoryRole -DirectoryRoleId <directoryRoleId>

Parameters:

• -DirectoryRoleId: The unique ID (GUID) of the directory role you want to retrieve.

Usage Examples

Get All Directory Roles

Get-MgDirectoryRole | Select ID, DisplayName, Description

This command retrieves all active directory roles in your tenant along with their ID and description.

Get Directory Role by ID

Get-MgDirectoryRole -DirectoryRoleId  | Select ID, DisplayName, Description

Use this when you have the role ID and want to fetch details about that specific role.

Get Directory Role by Display Name

Get-MgDirectoryRole | Where-Object { $_.DisplayName -eq "Global Administrator" } | Select *

Searches for a directory role with the exact display name, such as "Global Administrator".

Finding Users With Directory Roles In Your Tenant

To list users who are assigned to directory roles, use Get-MgDirectoryRoleMember alongside Get-MgDirectoryRole:

$roles = Get-MgDirectoryRole
foreach ($role in $roles) {
    Write-Host "`nRole: $($role.DisplayName)"
    $members = Get-MgDirectoryRoleMember -DirectoryRoleId $role.Id
    foreach ($member in $members) {
        Write-Output " - $($member.AdditionalProperties.displayName) ($($member.AdditionalProperties.userPrincipalName))"
    }
}
                                        

This script loops through each directory role and displays the display name and UPN of every user assigned to it.

💡 Note: The AdditionalProperties property is where user details like displayName and userPrincipalName are stored.

Frequently Asked Questions

• Why don't I see all roles in my tenant?

Only active roles (those with assigned members) appear with Get-MgDirectoryRole.

• How can I list all possible roles, even if they're not in use?

Use Get-MgDirectoryRoleTemplate to retrieve a complete list of available role templates.

• How do I assign a user to a directory role?

Use New-MgDirectoryRoleMemberByRef with the directory role ID and the user's object ID.

Use Cases

• Security Audits: Check who holds critical admin roles like Global Admin or Privileged Role Admin.
• Automation: Generate reports for compliance or routine internal governance.
• Onboarding: Ensure new admins are properly assigned to required roles.
• Offboarding: Revoke directory roles as part of user deprovisioning.

Conclusion

The Get-MgDirectoryRole cmdlet is your go-to tool for fetching activated directory roles in Microsoft 365. When paired with Get-MgDirectoryRoleMember, you gain full visibility into who has administrative access and can make informed decisions about role-based access control.

Whether you're auditing, securing, or reporting, these tools are essential for any Microsoft 365 administrator.