How to Use New-MgDirectoryRole to Create Directory Roles?

When managing access and roles in Microsoft 365 and Azure Active Directory (AAD), there are times you’ll need to activate a directory role before assigning it to users. That’s exactly what the New-MgDirectoryRole cmdlet is designed to do.

In this article, we'll explain what this cmdlet is, why it matters, how to use it, and share a few practical examples to help you get started.

What is New-MgDirectoryRole?

New-MgDirectoryRole is a Microsoft Graph PowerShell cmdlet that allows administrators to activate a directory role in Azure Active Directory based on a predefined directory role template.

Each role (e.g., Exchange Administrator, Conditional Access Administrator) has a corresponding template, and roles cannot be assigned until they are first activated using this cmdlet.

Once activated, these roles become visible in your tenant and can be assigned to users via the Microsoft 365 admin center or programmatically through PowerShell.

Why Use New-MgDirectoryRole?

There are several key reasons why you might use this cmdlet:

• Enable Role Assignment: You can't assign a role unless it has been activated.
• Automation: Ideal for scripts that configure access during tenant setup or restructuring.
• Governance: Enables programmatic control over which roles are enabled in your environment.
• Custom Deployment: Activating only required roles reduces attack surface and enforces least-privilege principles.

Cmdlet Syntax

New-MgDirectoryRole -BodyParameter <hashtable>

Required Parameter:

• -BodyParameter: A hashtable that must include the roleTemplateId of the role you wish to activate.

Usage Examples

Example 1: Create a Directory Role (Global Reader)

Import-Module Microsoft.Graph.Identity.DirectoryManagement

$params = @{
    roleTemplateId = "fe930be7-5e62-47db-91af-98c3a49a38b1"
}
New-MgDirectoryRole -BodyParameter $params
                                        

This activates the Global Reader role in your tenant using its template ID.

Tip: You can use Get-MgDirectoryRoleTemplate to list all available role templates and their IDs.

Frequently Asked Questions

• Can I activate the same role more than once?

No. A directory role template can only be activated once. Trying to activate it again will result in an error.

• Where can I get the roleTemplateId values?

Use the following command:

Get-MgDirectoryRoleTemplate | Select-Object DisplayName, Id

• Is admin permission required?

Yes, you need appropriate directory-level permissions such as RoleManagement.ReadWrite.Directory.

Use Cases

Here are some real-world scenarios where New-MgDirectoryRole is useful:

• Tenant Setup Automation: Quickly enable key roles during initial setup.
• Security & Compliance: Ensure only essential roles are activated to reduce risk.
• Delegated Admin Setup: Enable roles before assigning them to regional or group-based admins.
• Custom Role Workflows: Integrate role creation into broader identity governance workflows.

Conclusion

The New-MgDirectoryRole cmdlet is essential for any admin who wants to activate and assign roles in Azure AD securely and programmatically. By leveraging this cmdlet in your automation scripts or governance workflows, you ensure that your role management is consistent, secure, and scalable.

Want to go further? Combine this with New-MgDirectoryRoleMemberByRef to assign the activated roles to users seamlessly!