Using Get-MgDirectoryRole in Graph PowerShell
The Get-MgDirectoryRole cmdlet in Graph PowerShell can be used to list all directory roles or retrieve information about a specific role by its ID. This is useful for managing and auditing role-based access within your organization.
Prerequisites
To use the Get-MgDirectoryRole cmdlet,
- You need one of the following Azure AD roles: Global administrator, Privileged role administrator, Directory Readers or Reports Reader (these roles provide the necessary permissions to read directory role information).
- You should possess "Directory.Read.All" Graph API permission scope. This scope allows reading of all directory roles.
Basic Syntax
Here’s the basic syntax of the Get-MgDirectoryRole cmdlet: Get-MgDirectoryRole [-DirectoryRoleId
] [<CommonParameters>]
- Get-MgDirectoryRole: This is the cmdlet used to retrieve information about directory roles (also known as Azure AD roles) in your Microsoft 365 tenant.
- -DirectoryRoleId <String>: This optional parameter allows you to specify the ID of a specific directory role you want to retrieve. If you don't provide this parameter, the cmdlet will return all directory roles in your tenant.
- -DirectoryRoleId: This is the name of the parameter.
- : This indicates that the parameter accepts a string value, which should be the ID of the directory role.
- <CommonParameters>:These are common parameters supported by many PowerShell cmdlets. They provide additional functionality such as specifying the output format, error handling, and more.
Get All Directory Roles
Just execute Get-MgDirectoryRole without any id to list all the directory roles in your tenant.
Note:: Get-MgDirectoryRole returns only activated roles in your tenant. A role is activated when a user or group is added to that role.
Get Directory Role by ID
Pass in the Directory Role ID to get information about that specific role.
Get Directory Role by Display Name
You can also find a role or get more information about a role using its display name.
Finding Users With Directory Roles In Your Tenant
To check which users have been assigned specific directory roles, you'll need to use a combination of Get-MgDirectoryRole, Get-MgDirectoryRoleMember and Get-MgUser cmdlets.
- Get-MgDirectoryRole - to get the activated roles in the tenant
- Get-MgDirectoryRoleMember - to list the members associated with those roles.
- Get-MgUser - to query the user details for each member (because Get-MgDirectoryRoleMember cmdlet might not return user details directly).
Here is the script that retrieves directory roles and their members, and exports the data to a CSV file:
How the Script Works?
The script does the following:
- Connects to Graph PowerShell with the required permissions: RoleManagement.Read.Directory and Directory.Read.All
- Fetches all the available directory roles and stores it in $directoryRoles variable.
- Loops through $directoryRoles variable and fetches the role members using Get-MgDirectoryRoleMember cmdlet (along with the role name and ID).
- Then uses Get-MgUser cmdlet to get the member DisplayName and UserPrincipalName, stores it in the $roleMembers variable. $roleMembers is a custom PS Object which also contains the RoleName.
- Finally, the fetched details are exported to a CSV file named DirectoryRoleMembersReport.csv
Tips for Using Get-MgDirectoryRole
Here are some tips to keep in mind while using the Get-MgDirectoryRole cmdlet in Microsoft Graph PowerShell:
- Ensure Appropriate Permissions: Make sure you have the necessary permissions to run the Get-MgDirectoryRole cmdlet. Typically, you need the RoleManagement.Read.Directory permission. If you need to retrieve detailed user information, you might also require Directory.Read.All.
-
Handling Large Tenants: For large tenants with many roles, the output can be extensive. Use pagination or filtering techniques to manage and process the data effectively.
- Combining with Other Cmdlets: Combine Get-MgDirectoryRole with other cmdlets like Get-MgDirectoryRoleMember to get detailed information about role members.
- Exporting Data: Export the retrieved role information to a CSV file for further analysis and reporting. This is useful for audits and compliance checks.
- Script Automation: Integrate Get-MgDirectoryRole into automation scripts to regularly check and report on directory roles. This helps maintain security and compliance.
Use Cases
- Identifying Directory Role Assignments: Administrators can use Get-MgDirectoryRole to list all directory roles in their organization. This helps to ensure that key roles, such as Global Administrator or Security Administrator, are assigned to the correct users and groups.
- Auditing Privileged Role Access: The cmdlet is useful for auditing and reviewing privileged roles, such as Azure AD Roles. Regular audits help organizations maintain security by ensuring that only authorized personnel have access to high-privilege roles.
- Delegating Role Management: This cmdlet can help determine which roles are available for delegation. Based on the role information, IT teams can assign users to roles that allow for role-specific management, enhancing productivity without giving full admin rights.
- Security Compliance Reporting: Using Get-MgDirectoryRole, administrators can generate reports on who has elevated privileges in the directory. These reports can be shared with security or compliance teams to maintain organizational standards.
- Automating Role Management: PowerShell scripts that use Get-MgDirectoryRole can be automated to manage and monitor directory roles. For instance, you can automate a process to notify administrators if any unexpected role assignments are made.
Possible Errors and Solutions
Error: Request_ResourceNotFound (404)
Cause: This error occurs if the requested directory role does not exist or is incorrectly specified in the -Filter parameter.
Solution: Ensure that the directory role exists and verify the spelling or syntax used in the filter query.
Get-MgDirectoryRole -Filter "DisplayName eq 'Global Administrator'"
Error: Insufficient privileges to complete the operation (403)
Cause: The account being used does not have the required privileges to retrieve directory roles.
Solution: Ensure the account used has the necessary permissions, such as a role with the Directory.Read.All scope or higher. Also, verify that the necessary permissions are granted to the application when using app-only authentication.
Error: Invalid filter clause (400)
Cause: This error is triggered when the filter condition is not formatted correctly.
Solution: Use correct OData filter syntax. For example, ensure that string values in filters are enclosed in single quotes.
Get-MgDirectoryRole -Filter "roleTemplateId eq '62e90394-69f5-4237-9190-012177145e10'"
Conclusion
The Get-MgDirectoryRole cmdlet is an essential tool for managing and monitoring directory roles in Microsoft 365. It provides administrators with the ability to audit role assignments, ensure security compliance, and automate directory role management tasks. While errors can arise due to permission issues or incorrect filter syntax, these can be mitigated by following proper authentication and query practices. By effectively utilizing this cmdlet, administrators can ensure their organization's roles are well-managed and secure.
Related Articles:
Using Find-GraphMgPermission in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Using Get-MgUserLicenseDetail 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