Using Get-MgDirectoryRoleMember in Graph PowerShell

This guide demonstrates how to use the Get-MgDirectoryRoleMember cmdlet in Microsoft Graph PowerShell to retrieve members of Azure AD directory roles. Learn how to list role members, filter by roles, and export results with practical examples

The Get-MgDirectoryRoleMember cmdlet is a powerful tool within the Microsoft Graph PowerShell module used to retrieve members of a specific directory role. This cmdlet is particularly useful for IT administrators who need to manage and audit directory roles within their Microsoft 365 environment. This article will cover the syntax, usage examples, tips, use cases, possible errors, and solutions associated with the Get-MgDirectoryRoleMember cmdlet.

Cmdlet Syntax

Get-MgDirectoryRoleMember -DirectoryRoleId <String> [-Filter <String>] [-Search <String>] [-ExpandProperty <String[]>] [-Property <String[]>] [<CommonParameters>]

Parameters:

• -DirectoryRoleId <String>: (Required) The ID of the directory role to retrieve members from.
• -Filter <String>: (Optional) OData filter query to filter the results.
• -Search <String>: (Optional) Search query to search for specific members.
• -ExpandProperty <String[]>: (Optional) Related entities to expand in the response.
• -Property <String[]>: (Optional) Properties to include in the response.

Usage Examples

Example 1: Retrieve All Members of a Directory Role

$roleId = "f8cdef31-a31e-4b4a-93e4-5f571e91255a" # Replace with the actual DirectoryRoleId
Get-MgDirectoryRoleMember -DirectoryRoleId $roleId

Example 2: Retrieve Specific Properties of Directory Role Members

To get detailed information about the members like ID, DisplayName, UserPrincipalName, you will need to use the Get-MgUser cmdlet in combination with Get-MgDirectoryRoleMember. First, retrieve the members and then fetch their details using Get-MgUser.

$roleId = "f8cdef31-a31e-4b4a-93e4-5f571e91255a" # Replace with the actual DirectoryRoleId
$members = Get-MgDirectoryRoleMember -DirectoryRoleId $roleId
foreach ($member in $members) {
    Get-MgUser -UserId $member.Id | Select-Object Id, DisplayName, UserPrincipalName
}

Example 3: Filtering based on Specific Properties of Directory Role Members

Note: Filtering based on specific properties of members directly within Get-MgDirectoryRoleMember is not directly supported. Instead, retrieve all members and filter the results afterward.

$roleId = "f8cdef31-a31e-4b4a-93e4-5f571e91255a" # Replace with the actual DirectoryRoleId
$members = Get-MgDirectoryRoleMember -DirectoryRoleId $roleId
$filteredMembers = foreach ($member in $members) {
    $user = Get-MgUser -UserId $member.Id
    if ($user.DisplayName -like "Admin*") {
        $user
    }
}
$filteredMembers | Select-Object Id, DisplayName, UserPrincipalName

Example 4: Retrieve Members with Manager Details Using -ExpandProperty

This script retrieves the members of a specific directory role and then expands the manager property to get the manager details. It constructs a custom object to display the user's details along with their manager's display name.

$roleId = "f8cdef31-a31e-4b4a-93e4-5f571e91255a" # Replace with the actual DirectoryRoleId
$members = Get-MgDirectoryRoleMember -DirectoryRoleId $roleId
foreach ($member in $members) {
    $userWithManager = Get-MgUser -UserId $member.Id -ExpandProperty "manager"
    if ($userWithManager.Manager) {
        $managerDisplayName = $userWithManager.Manager.AdditionalProperties["displayName"]
        [PSCustomObject]@{
            UserId             = $userWithManager.Id
            DisplayName        = $userWithManager.DisplayName
            UserPrincipalName  = $userWithManager.UserPrincipalName
            ManagerDisplayName = $managerDisplayName
        }
    }
}

Cmdlet Tips

• Use Proper Filtering: Utilize the -Filter parameter to narrow down results and improve performance.
• Select Specific Properties: Use the -Select parameter to retrieve only the necessary properties, reducing the amount of data returned.
• Consistency Level: If performing large queries, consider using -ConsistencyLevel eventual to optimize performance.
• Expand Related Entities: Use the -ExpandProperty parameter to include related entities in the response, which can be useful for more detailed information.

Use Cases

• Role Management: Retrieve and audit members of critical roles like Global Administrator, ensuring only authorized users are included.
• Security Audits: Regularly check members of directory roles to maintain security and compliance.
• Automated Reporting: Integrate with automation scripts to generate regular reports on directory role memberships.

Possible Errors & Solutions

Get-MgDirectoryRole | Select-Object Id, DisplayName

Frequently Asked Questions

• What is Get-MgDirectoryRoleMember used for?
  Get-MgDirectoryRoleMember is a Microsoft Graph PowerShell cmdlet used to list members of specific Azure AD directory roles, such as Global Administrator or User Administrator.
• How can I list members of a specific directory role?
  Use the following script to retrieve members of a role by its ID:

  Get-MgDirectoryRoleMember -DirectoryRoleId "<RoleId>"

• Can I export directory role members to a CSV file?
  Yes, use this script to export members of a role:

  $Members = Get-MgDirectoryRoleMember -DirectoryRoleId "<RoleId>"
  $Members | Select-Object DisplayName, UserPrincipalName, Id | Export-Csv -Path "C:\Path\To\DirectoryRoleMembers.csv" -NoTypeInformation

• What permissions are required to use Get-MgDirectoryRoleMember?
  You need the Directory.Read.All or Directory.ReadWrite.All permission in Microsoft Graph PowerShell. Ensure these permissions are granted in Azure AD.

Conclusion

The Get-MgDirectoryRoleMember cmdlet is an essential tool for managing and auditing directory role memberships in Microsoft 365. By understanding its syntax, usage, and common issues, administrators can effectively leverage this cmdlet to enhance their role management processes. Regular audits and automated reporting using this cmdlet can help maintain a secure and compliant Microsoft 365 environment.

For more detailed information and additional examples, refer to the official Microsoft documentation: Get-MgDirectoryRoleMember

Related Articles: