How to Use New-MgDirectoryRoleMemberByRef to Assign Microsoft 365 Directory Roles?

Managing admin access in Microsoft 365 is a critical task for any IT administrator. Assigning users or service principals to specific directory roles—like Global Administrator or Application Administrator—ensures proper access control and delegation.

In this blog, you’ll learn how to use the powerful New-MgDirectoryRoleMemberByRef cmdlet from the Microsoft Graph PowerShell SDK to safely and accurately assign directory roles in your tenant.

What is New-MgDirectoryRoleMemberByRef?

The New-MgDirectoryRoleMemberByRef cmdlet is part of the Microsoft Graph PowerShell module. It allows you to assign a directory object—such as a user or a service principal (app)—to a directory role.

Instead of directly specifying the user ID or service principal ID in parameters, it uses the @odata.id format in the body to reference the directory object you want to assign.

Why Use New-MgDirectoryRoleMemberByRef?

Here are some of the reasons why this cmdlet is useful:

• Assign administrative roles to users or apps in a secure and automated manner.
• Automate role assignment during provisioning workflows.
• Ensure least privilege access by managing role assignments programmatically.
• Meet audit and compliance requirements through consistent role tracking.

Cmdlet Syntax

New-MgDirectoryRoleMemberByRef -DirectoryRoleId <String> -BodyParameter <IMicrosoftGraphDirectoryObject>

Parameters:

• -DirectoryRoleId: The unique ID of the activated directory role.
• -BodyParameter: A hashtable that references the directory object (user, servicePrincipal, etc.) via its @odata.id property.

Usage Examples

Adding a User to a Directory Role

The following example assigns a user to the Global Administrator role.

# Get the role ID for Global Administrator
$roleId = (Get-MgDirectoryRole -Filter "displayName eq 'Global Administrator'").Id
                                            
# Build the body with the user’s object ID
$body = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/2d6a3dc5-36af-494b-aebd-e2dd179077b2"
}
                                            
# Assign the user to the role
New-MgDirectoryRoleMemberByRef -DirectoryRoleId $roleId -BodyParameter $body
# Replace the object ID with the one corresponding to the user you want to assign.
                                        

Adding a Service Principal to a Directory Role

To assign a service principal (app registration) to the Application Administrator role:

# Get the role ID for Application Administrator
$roleId = (Get-MgDirectoryRole -Filter "displayName eq 'Application Administrator'").Id
                                            
# Build the body with the service principal’s object ID
$body = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/00000000-0000-0000-0000-000000000000"
}
                                            
# Assign the service principal to the role
New-MgDirectoryRoleMemberByRef -DirectoryRoleId $roleId -BodyParameter $body
                                        

📌 Note: The object ID used here should be the Service Principal ID, not the Application ID.

Frequently Asked Questions

• Do I need to activate a directory role before assigning members?

Yes. Roles must be activated (at least one user assigned) to appear in Get-MgDirectoryRole. Use Activate-MgDirectoryRole if needed.

• What happens if I try to assign the same user twice?

No error will be thrown, but duplicates are silently ignored.

• Can I remove a role assignment?

Yes. Use Remove-MgDirectoryRoleMemberByRef to remove a user or service principal from a role.

Use Cases

• Delegating administration during onboarding of new IT staff
• Assigning service principals to automate secure back-end operations
• Automating tenant setup or security baseline deployments
• Ensuring privileged roles are not left unassigned

Conclusion

The New-MgDirectoryRoleMemberByRef cmdlet is an essential tool for secure and automated role assignment in Microsoft 365. Whether you're assigning a user as a Global Administrator or granting an app elevated privileges, this cmdlet gives you precise, programmable control over directory role management.

By leveraging Microsoft Graph PowerShell, you ensure your tenant’s access policies are not just secure—but also scalable and compliant.