List All Azure AD Role Definitions Using Graph PowerShell

Before assigning or auditing Azure AD directory roles, administrators often need a complete list of all available roles, along with their definitions — whether they are Microsoft-defined (built-in) or custom-created. This script leverages the Get-MgRoleManagementDirectoryRoleDefinition cmdlet from Microsoft Graph PowerShell to retrieve and present these roles clearly.

The Script: Retrieve Directory Role Definitions

# Connect to Microsoft Graph with necessary permissions
Connect-MgGraph -Scopes "RoleManagement.Read.Directory"
                                
# Retrieve all directory role definitions
$roleDefinitions = Get-MgRoleManagementDirectoryRoleDefinition -All
                                
# Format the output with useful columns
$formatted = $roleDefinitions | Select-Object `
Id,
DisplayName,
Description,
IsBuiltIn,
RolePermissions
                                
# Display results in table format
$formatted | Format-Table -AutoSize
                                
# Optional: Export to CSV
# $formatted | Export-Csv -Path "AllDirectoryRoleDefinitions.csv" -NoTypeInformation
                                

How the Script Works

Here’s what this script does step by step:

1. Establishes a Connection

Uses Connect-MgGraph with the required scope (RoleManagement.Read.Directory) to query role-related metadata.

2. Fetches All Role Definitions

The Get-MgRoleManagementDirectoryRoleDefinition -All cmdlet returns every directory role available in Azure AD — including both built-in roles (like Global Administrator) and custom roles.

3. Selects Key Properties

Using Select-Object, the script extracts relevant properties:

• Id: Unique identifier used during assignments
• DisplayName: Human-readable role name
• Description: Overview of what the role permits
• IsBuiltIn: Indicates whether the role is native or custom
• RolePermissions: List of allowed actions (summarized)
4. Outputs to Console or CSV

Results are shown as a clean table, with an optional export to CSV for documentation or audits.

Further Enhancements

• Filter Built-In Roles Only:

$roleDefinitions | Where-Object { $_.IsBuiltIn -eq $true }

• List Only Custom Roles:

$roleDefinitions | Where-Object { $_.IsBuiltIn -eq $false }

• Search Roles by Keyword (e.g., Admin):

$roleDefinitions | Where-Object { $_.DisplayName -like "*Admin*" }

• Expand RolePermission nto readable actions (advanced enhancement):
You can loop through each RolePermissions entry and parse the allowed actions using:

$role.RolePermissions.AllowedResourceActions

Use Cases

Here’s why this script is valuable to Microsoft 365 admins and security teams:

• Look Up Role IDs for Assignment: Required for cmdlets like New-MgRoleManagementDirectoryRoleAssignment
• Audit Available Roles: Useful for governance teams reviewing RBAC models
• Document Directory Roles: Export all available roles to CSV for security reports
• Explore Custom Roles: Quickly identify organization-specific roles (IsBuiltIn = False)

Possible Errors & Solutions

Error Message	Cause	Solution
Access Denied	Missing required Graph permissions	Use -Scopes "RoleManagement.Read.Directory" when connecting
The term 'Get-MgRoleManagementDirectoryRoleDefinition' is not recognized	Graph module not installed or loaded correctly	Run Install-Module Microsoft.Graph -Scope CurrentUser and Import-Module Microsoft.Graph
Empty Output	No roles returned or filtering too early	Use -All and ensure role permissions are enabled

Conclusion

The Get-MgRoleManagementDirectoryRoleDefinition cmdlet is your go-to tool for discovering all assignable roles in Azure AD — both built-in and custom. Whether you're assigning roles, auditing access, or managing custom role creation, this script gives you clear visibility into the complete RBAC role catalog available in your tenant.

It works perfectly alongside:

• Get-MgRoleManagementDirectoryRoleAssignment – to see who holds these roles
• New-MgRoleManagementDirectoryRoleAssignment – to assign roles using the retrieved Id

By integrating this script into your admin workflow, you can confidently manage and govern directory roles with precision.