How to Use Get-MgRoleManagementDirectoryRoleDefinition to Fetch Directory Role Definitions?

Microsoft Entra ID (formerly known as Azure Active Directory) provides a rich set of directory roles to help you manage access and permissions at scale. Whether it's built-in roles like Global Administrator or custom-defined roles tailored to your organization’s needs, it’s important to be able to retrieve, review, and understand these roles effectively.

This blog introduces the Get-MgRoleManagementDirectoryRoleDefinition cmdlet — your go-to command for fetching directory role definitions using Microsoft Graph PowerShell.

What is Get-MgRoleManagementDirectoryRoleDefinition?

Get-MgRoleManagementDirectoryRoleDefinition is a Microsoft Graph PowerShell cmdlet that allows you to list all the role definitions available in your tenant. These definitions represent all the available directory-level roles, including:

• Built-in roles like Global Administrator, Security Reader, etc.
• Custom roles created for specific organizational needs.

Each role definition includes properties like:

• Id – Unique identifier of the role
• DisplayName – Name of the role
• Description – What the role does
• IsBuiltIn – Whether it’s a built-in or custom role

Why Use Get-MgRoleManagementDirectoryRoleDefinition?

There are several reasons why administrators and auditors would want to use this cmdlet:

• Compliance – List all roles to verify what permissions exist in the tenant
• Troubleshooting – Understand what permissions are included in each role
• Role Mapping – Match role assignments (via Get-MgRoleManagementDirectoryRoleAssignment) to friendly role names
• Custom Role Discovery – Identify roles created specifically for your organization

Cmdlet Syntax

Get-MgRoleManagementDirectoryRoleDefinition

With All Switch:

Get-MgRoleManagementDirectoryRoleDefinition -All

The -All switch is useful when you want to retrieve every role definition across your tenant without pagination.

Usage Examples

Get All Directory Role Definitions

Get-MgRoleManagementDirectoryRoleDefinition -All |
Select-Object Id, DisplayName, Description, IsBuiltIn
                                        

This gives you a comprehensive view of every role available in your tenant.

Query Directory Role Definitions Based on Display Name

$roleDefinitions = Get-MgRoleManagementDirectoryRoleDefinition -All
$roleDefinitions | Where-Object { $_.IsBuiltIn -eq $false }
                                        

Use this when you're looking for roles like “Global Administrator” or anything containing "Global".

Query for Custom Directory Role Definitions

$roleDefinitions = Get-MgRoleManagementDirectoryRoleDefinition -All
$roleDefinitions | Where-Object { $_.IsBuiltIn -eq $false }
                                        

This filters out built-in roles, showing only the custom directory roles defined in your organization.

Frequently Asked Questions

🔸 What is the difference between a role definition and a role assignment?

• A role definition is a template that defines the permissions.
• A role assignment connects a user/group to that definition at a given scope.

🔸 Can I retrieve role definitions by name using a filter?

Currently, -Filter is not supported directly for this cmdlet. Use the -All switch and pipe to Where-Object in PowerShell, as shown in the examples.

🔸 How do I know if a role is built-in or custom?

Each role object has an IsBuiltIn property:

• True = Built-in
• False = Custom

Use Cases

• Access Governance: Build reports of all available roles and their descriptions.
• Security Hardening: Identify unused or overly permissive roles.
• Custom Role Validation: List and audit all custom roles and their permissions./li>
• Helpdesk Tooling: Create admin tools that query role definitions for assignment workflows.

Conclusion

The Get-MgRoleManagementDirectoryRoleDefinition cmdlet is an essential tool for discovering, understanding, and auditing directory roles in Microsoft Entra ID. Whether you're running a security review, building automation, or creating a role assignment interface, this cmdlet gives you the foundational knowledge needed to work with Azure AD roles intelligently.

Start exploring your directory roles today — and combine this with Get-MgRoleManagementDirectoryRoleAssignment for a complete role-to-user mapping!