Using Get-MgDirectoryRoleMember in Graph PowerShell

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

Error: "The specified directory role does not exist."

Cause: The DirectoryRoleId provided is incorrect or the role does not exist in the directory.

Solution: Verify the DirectoryRoleId by retrieving all directory roles using the Get-MgDirectoryRole cmdlet.

Get-MgDirectoryRole | Select-Object Id, DisplayName

Error: "Insufficient privileges to complete the operation."

Cause: The account running the cmdlet does not have the necessary permissions.

Solution: Ensure the account has the appropriate roles assigned, such as Global Administrator or Privileged Role Administrator.

Error: "Invalid filter clause."

Cause: The syntax of the -Filter parameter is incorrect or the filtering on reference properties is not supported.

Solution: Review the OData filter query syntax and correct any errors. Use alternative methods such as filtering the results after retrieving them.


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:

Using Get-MgDirectoryRole in Graph PowerShell
Using Get-MgUserLicenseDetail in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Connect to Microsoft 365 Using PowerShell
How to Create Bulk Users in Office 365 Using Graph PowerShell?
Create Microsoft 365 Group Using Microsoft Graph PowerShell
Block Microsoft 365 User Using Microsoft Graph PowerShell
Assign Microsoft 365 License Using Graph PowerShell
Microsoft 365 User Management Using Graph PowerShell
Checking Group Membership in Microsoft 365
Bulk Assign Microsoft 365 License
Find Inactive Users in Microsoft 365
Using Powershell Graph Search Query
Using Powershell Graph Filter Query
Using Where-Object In Graph PowerShell
Using Expand Property In Graph PowerShell
Using Select Object In Graph PowerShell
Using -Contains Operator In Graph PowerShell
Add User to Multiple Microsoft 365 Groups Using Graph PowerShell
Get Microsoft 365 User Location Using Graph PowerShell
Import Microsoft 365 Groups from CSV File Using Graph PowerShell
Microsoft 365 Group User Import Using Graph PowerShell

© m365corner.com. All Rights Reserved. Design by HTML Codex