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.
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.$roleId = "f8cdef31-a31e-4b4a-93e4-5f571e91255a" # Replace with the actual DirectoryRoleId
Get-MgDirectoryRoleMember -DirectoryRoleId $roleId
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
}
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
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
}
}
}
-Filter
parameter to narrow down results and improve performance.-Select
parameter to retrieve only the necessary properties, reducing the amount of data returned.-ConsistencyLevel eventual
to optimize performance.-ExpandProperty
parameter to include related entities in the response, which can be useful for more detailed information.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
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.
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.
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
© m365corner.com. All Rights Reserved. Design by HTML Codex