New-MgRoleManagementDirectoryRoleDefinition: Create Custom Directory Roles with Graph PowerShell

Azure AD allows administrators to define custom directory roles that fit unique organizational requirements. The New-MgRoleManagementDirectoryRoleDefinition cmdlet enables you to create these roles using Microsoft Graph PowerShell — assigning only the required permissions and limiting unnecessary access.

This cmdlet is essential when adhering to least-privilege principles while still granting functionality to specific teams or tools.

Cmdlet Syntax

New-MgRoleManagementDirectoryRoleDefinition -BodyParameter <hashtable>

Usage Examples

Example 1: Create a Role for Application Registration Support

Import-Module Microsoft.Graph.Identity.Governance
$params = @{
description = "Update basic properties of application registrations"
displayName = "Application Registration Support Administrator"
rolePermissions = @(
    @{
        allowedResourceActions = @(
        "microsoft.directory/applications/basic/read"
        )
    }
)
isEnabled = $true
}
                                
New-MgRoleManagementDirectoryRoleDefinition -BodyParameter $params
                            

This role allows limited read-only access to basic app registration data.

Example 2: Create a Role with Group Membership Management Rights

$params = @{
description = "Custom role to allow group membership management"
displayName = "Group Membership Manager"
rolePermissions = @(
@{
    allowedResourceActions = @(
        "microsoft.directory/groups/basic/read",
        "microsoft.directory/groups/members/update"
    )
}
)
isEnabled = $true
}
                            
New-MgRoleManagementDirectoryRoleDefinition -BodyParameter $params
                            

This role allows users to read group info and update group members (but not owners or group settings).

Cmdlet Tips

• Use the allowedResourceActions array to fine-tune the permissions granted by your custom role.
• Combine this cmdlet with New-MgRoleManagementDirectoryRoleAssignment to assign the new role to users or groups.
• Always set isEnabled = $true or the role will be created in a disabled state.
• Use Get-MgRoleManagementDirectoryRoleDefinition to validate and list your custom roles after creation.

Use Cases

This script is highly useful for the following real-world scenarios:

• Helpdesk Delegation: Provide limited permissions for tier-1 support agents.
• Custom Audit Roles: Create read-only roles for security or compliance teams.
• Scoped Group/Device Management: Enable IT operations teams to manage specific resources.
• Third-Party App Permissions: Create roles tailored for service principals running custom automation.

Possible Errors & Solutions

Error Message	Cause	Solution
Access Denied	Insufficient privileges or missing API permissions	Use Graph scopes: RoleManagement.ReadWrite.Directory
InvalidRequest: allowedResourceActions is null or empty	Missing permissions block in role definition	Ensure allowedResourceActions has at least one valid action
ResourceNotFound	Misspelled or unsupported action name	Use official permission list
Request_BadRequest: Role definition already exists	Duplicate display name	Use a unique displayName for each role

Conclusion

The New-MgRoleManagementDirectoryRoleDefinition cmdlet empowers administrators to create custom directory roles tailored to organizational needs. By specifying precise resource actions, it supports granular access control and promotes least privilege in Microsoft 365 environments.

This cmdlet works seamlessly with:

• Get-MgRoleManagementDirectoryRoleDefinition – to list or audit custom roles
• New-MgRoleManagementDirectoryRoleAssignment – to assign new roles

Custom roles are a powerful feature, especially for delegation, automation, and compliance-driven RBAC models. If your admin model demands flexibility without compromising security — this cmdlet is a must-have in your toolkit.