New-MgRoleManagementDirectoryRoleAssignment: Assign Azure AD Roles Using Graph PowerShell

The New-MgRoleManagementDirectoryRoleAssignment cmdlet allows administrators to assign directory roles (like Global Administrator, Reports Reader, or Application Administrator) to users, groups, or service principals. This role assignment can be scoped to the entire directory, an administrative unit, or even an application.

In this article, we’ll walk through practical usage scenarios, syntax structure, assignment types, and best practices.

Cmdlet Syntax

New-MgRoleManagementDirectoryRoleAssignment -BodyParameter <hashtable>

Usage Examples

Example 1: Assign a Role with Tenant Scope

Import-Module Microsoft.Graph.Identity.Governance
$params = @{
    "@odata.type"      = "#microsoft.graph.unifiedRoleAssignment"
    roleDefinitionId   = "c2cf284d-6c41-4e6b-afac-4b80928c9034"  # Role ID (e.g., Reports Reader)
    principalId        = "f8ca5a85-489a-49a0-b555-0a6d81e56f0d"  # User/Group/SP ID
    directoryScopeId   = "/"                                    # Tenant-wide
}
New-MgRoleManagementDirectoryRoleAssignment -BodyParameter $params
                            

Example 2: Assign a Role at Administrative Unit Scope

$params = @{
    "@odata.type"      = "#microsoft.graph.unifiedRoleAssignment"
    roleDefinitionId   = "fe930be7-5e62-47db-91af-98c3a49a38b1"  # Global Admin
    principalId        = "f8ca5a85-489a-49a0-b555-0a6d81e56f0d"
    directoryScopeId   = "/administrativeUnits/5d107bba-d8e2-4e13-b6ae-884be90e5d1a"
}
New-MgRoleManagementDirectoryRoleAssignment -BodyParameter $params
                            

Example 3: Assign a Role to an App (Application Scope)

$params = @{
    "@odata.type"      = "#microsoft.graph.unifiedRoleAssignment"
    principalId        = "6b937a9d-c731-465b-a844-2d5b5368c161"  # Service Principal
    roleDefinitionId   = "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3"  # App Role
    directoryScopeId   = "/661e1310-bd76-4795-89a7-8f3c8f855bfc"  # App scope
}
New-MgRoleManagementDirectoryRoleAssignment -BodyParameter $params
                            

Example 4: Assign a Directory Role to a Single User

# Lookup role ID and user ID beforehand using Get-MgRoleManagementDirectoryRoleDefinition and Get-MgUser
$params = @{
    "@odata.type"      = "#microsoft.graph.unifiedRoleAssignment"
    roleDefinitionId   = "c2cf284d-6c41-4e6b-afac-4b80928c9034"  # Reports Reader
    principalId        = (Get-MgUser -UserId "john.doe@contoso.com").Id
    directoryScopeId   = "/"
}
New-MgRoleManagementDirectoryRoleAssignment -BodyParameter $params
                            

Example 5: Bulk Assign a Role to Multiple Users (CSV Input)

CSV Format:

UserPrincipalName
alice@contoso.com
bob@contoso.com
charlie@contoso.com

Script:

$roleDefinitionId = "c2cf284d-6c41-4e6b-afac-4b80928c9034"  # Reports Reader

Import-Csv "./users.csv" | ForEach-Object {
$userId = (Get-MgUser -UserId $_.UserPrincipalName).Id
                                
$params = @{
    "@odata.type"      = "#microsoft.graph.unifiedRoleAssignment"
    roleDefinitionId   = $roleDefinitionId
    principalId        = $userId
    directoryScopeId   = "/"
}
                                
New-MgRoleManagementDirectoryRoleAssignment -BodyParameter $params
}
                            

Cmdlet Tips

You can tailor this script to extract more insight:

• Always lookup role IDs using Get-MgRoleManagementDirectoryRoleDefinition before assigning.
• Use Get-MgUser, Get-MgGroup, or Get-MgServicePrincipal to retrieve valid principal IDs.
• Ensure scopes are valid:
• / = Tenant scope
• /administrativeUnits/{AU-ID} = Admin unit
• /{appId} = Application scope

Use Cases

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

• 🔐 Assign Global Admin role to a break-glass or emergency account.
• 🛡️ Delegate Reports Reader to non-admin staff for compliance purposes.
• 🏛️ Scope User Admin rights to a specific Administrative Unit (e.g., HR).
• 🔄 Bulk role assignment during onboarding of support engineers.
• 📦 Grant app-specific roles to automation/service principals securely.

Possible Errors & Solutions

Error Message	Cause	Solution
Access Denied	Insufficient permissions	Use Directory.AccessAsUser.All or RoleManagement.ReadWrite.Directory scope
InvalidRequest: Cannot assign the role	Incorrect role scope or unsupported role assignment target	Confirm the role supports your target (user/group/SP) and scope
Missing or invalid directoryScopeId	Wrong format for admin unit or app scope	Use /administrativeUnits/{id} or /appId structure correctly
The specified role assignment already exists	Duplicate assignment	Check with Get-MgRoleManagementDirectoryRoleAssignment first

Conclusion

The New-MgRoleManagementDirectoryRoleAssignment cmdlet gives you fine-grained control over role assignments in Microsoft 365, allowing you to define who gets what role and at what scope — whether it’s tenant-wide, scoped to an administrative unit, or tied to an application.

With just a few lines of Graph PowerShell, administrators can now automate and audit role assignments, aligning perfectly with least privilege principles, delegated admin responsibilities, and governance policies.