How to create a directory role definition using Microsoft Graph PowerShell

The New-MgRoleManagementDirectoryRoleDefinition cmdlet is used to create a new custom role definition in Microsoft Entra ID (formerly Azure AD). Role definitions specify a collection of permissions and actions that admins can assign to users, groups, or service principals through role assignments. This cmdlet is useful when the built-in directory roles such as Global Administrator or User Administrator do not meet the organization’s exact needs. By creating custom roles, IT teams can follow the principle of least privilege, only granting users the permissions necessary for their job functions.

This article shows you how to create a directory role definition using both Microsoft Entra admin center and Microsoft Graph PowerShell:

Create a directory role definition using Microsoft Graph PowerShell

Prerequisites

Install Graph module with role management permissions:

Using the New-MgRoleManagementDirectoryRoleDefinition cmdlet

Run the script below by specifying role details and permission actions:

Examples

Example 1: Create a read-only custom role

Example 2: Create a role allowing user password resets

Example 3: Create a role with combined permissions

Supported parameters

The following essential parameters can be used along with the New-MgRoleManagementDirectoryRoleDefinition cmdlet:

Limitations of using native tools to create custom roles

• PowerShell commands can get complex with different use cases and scenarios.
• IT admins can spend a lot of time troubleshooting errors, which negatively impacts productivity.
• Delegation can get tricky since technicians require elevated permissions.