The New-MgDirectoryRole cmdlet is a powerful tool within the Microsoft Graph PowerShell module allowing administrators to create new directory roles in Azure Active Directory (AAD). This article covers the prerequisites, cmdlet syntax, usage examples (including bulk assigning roles to M365 users and assigning roles to M365 users by importing them from a CSV file), use cases, possible errors, and their solutions.
Before diving into the New-MgDirectoryRole cmdlet, ensure you meet the following prerequisites:
Install-Module Microsoft.Graph -Scope CurrentUser
Connect-MgGraph -Scopes "Directory.ReadWrite.All"
New-MgDirectoryRole -RoleTemplateId <String> [-InformationAction <ActionPreference>] [-InformationVariable <String>] [<CommonParameters>]
Parameters:
-RoleTemplateId:
Specifies the template ID of the role you want to create.-InformationAction:
Specifies how to respond to an information event (optional).-InformationVariable:
Specifies an information variable (optional).$roleTemplateId = "your-role-template-id"
New-MgDirectoryRole -RoleTemplateId $roleTemplateId
Note: The New-MgDirectoryRole cmdlet helps you create an instance of Azure Active Directory (AAD) roles (like Global admin, Exchange admin, etc.) via Graph PowerShell in your tenant. You need to pass in the RoleTemplateId parameter value to create the new directory role. To find out the RoleTemplateID you require, you should execute Get-MgDirectoryRoleTemplate cmdlet.
Note: You can verify whether the selected directory role has been added to your tenant by executing Get-MgDirectoryRole cmdlet.
To add multiple users to a directory role, you can first create the role and then use the New-MgDirectoryRoleMemberByRef cmdlet to add members to that role.
# Create a new directory role
$roleTemplateId = "your-role-template-id"
$directoryRole = New-MgDirectoryRole -RoleTemplateId $roleTemplateId
# Add multiple users to the role
$userIds = @("user1-object-id", "user2-object-id", "user3-object-id")
foreach ($userId in $userIds) {
New-MgDirectoryRoleMemberByRef -DirectoryRoleId $directoryRole.Id -UserId $userId
}
You can add users to a directory role from a CSV file. Ensure your CSV file has column headers UserPrincipalName and RoleTemplateId.
UserPrincipalName,RoleTemplateId
user1@example.com,62e90394-69f5-4237-9190-012177145e10
user2@example.com,62e90394-69f5-4237-9190-012177145e10
user3@example.com,62e90394-69f5-4237-9190-012177145e10
# Import users and roles from the CSV file
$users = Import-Csv -Path "path-to-your-csv-file.csv"
foreach ($user in $users) {
# Activate the directory role if not already activated
$role = Get-MgDirectoryRole | Where-Object { $_.RoleTemplateId -eq $user.RoleTemplateId }
if (-not $role) {
$role = New-MgDirectoryRole -RoleTemplateId $user.RoleTemplateId
}
# Get the user's object ID
$userId = (Get-MgUser -UserPrincipalName $user.UserPrincipalName).Id
# Add the user to the directory role
New-MgDirectoryRoleMemberByRef -DirectoryRoleId $role.Id -PrincipalId $userId
}
Solution: Ensure you have the necessary permissions (e.g., Global Administrator) to create directory roles.
Solution: Verify that the role template ID is correct and exists in your directory. Use Get-MgDirectoryRoleTemplate to list available templates.
Get-MgDirectoryRoleTemplate
Solution: Ensure that the user IDs you are adding to the directory role are correct and exist in your directory. You can verify user IDs using Get-MgUser.
Get-MgUser -UserId "user-principal-name"
The New-MgDirectoryRole cmdlet is an essential tool for Azure AD administrators, providing the ability to create and manage directory roles efficiently. By understanding its prerequisites, syntax, usage examples, and potential errors, you can leverage this cmdlet to enhance your directory management capabilities. Whether you're creating custom roles or automating role assignments, New-MgDirectoryRole can significantly streamline your administrative tasks.
© m365corner.com. All Rights Reserved. Design by HTML Codex