The New-MgDirectoryRoleMemberByRef cmdlet is a powerful tool within the Microsoft Graph PowerShell module designed to add members to a directory role by reference. This cmdlet is essential for IT administrators managing Microsoft 365 environments as it allows for precise and efficient role management.
Install-Module Microsoft.Graph -Scope CurrentUser
New-MgDirectoryRoleMemberByRef -DirectoryRoleId <String> -BodyParameter <IMicrosoftGraphDirectoryObject> [<CommonParameters>]
Parameters:
-DirectoryRoleId <String>:
Specifies the ID of the directory role to which the member is to be added.-BodyParameter <IMicrosoftGraphDirectoryObject>:
Specifies the directory object (usually a user or service principal) that will be added to the directory role.<CommonParameters>:
These are common parameters supported by Microsoft Graph PowerShell including -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, and -WarningAction.$roleId = (Get-MgDirectoryRole -Filter "displayName eq 'Global Administrator'").Id
$body = @{
"@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/2d6a3dc5-36af-494b-aebd-e2dd179077b2"
}
New-MgDirectoryRoleMemberByRef -DirectoryRoleId $roleId -BodyParameter $body
In this example, a user with the user ID 2d6a3dc5-36af-494b-aebd-e2dd179077b2
is added to the Global Administrator role. You can get the user ID using the Get-MgUser cmdlet.
$roleId = (Get-MgDirectoryRole -Filter "displayName eq 'Application Administrator'").Id
$body = @{
"@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/00000000-0000-0000-0000-000000000000"
}
New-MgDirectoryRoleMemberByRef -DirectoryRoleId $roleId -BodyParameter $body
Here, a service principal identified by its App ID is added to the Application Administrator role using its service principal ID 00000000-0000-0000-0000-000000000000
. You can get the service principal ID by using the Get-MgServicePrincipal
cmdlet.
Get-MgUser
for users and Get-MgServicePrincipal
for service principals to get their IDs. This is crucial for accurate member addition.-ErrorAction
and -Verbose
to manage errors and get detailed output for troubleshooting.Cause: This typically occurs if the specified role or user/service principal ID does not exist.
Solution:
Get-MgDirectoryRole
and Get-MgUser
or Get-MgServicePrincipal
to confirm the existence of these IDs.Cause: The executing account does not have the necessary permissions.
Solution:
The New-MgDirectoryRoleMemberByRef cmdlet is an essential tool for managing directory roles in a Microsoft 365 environment. By understanding its syntax, usage, and potential pitfalls, administrators can effectively manage role memberships, enhancing the security and efficiency of their IT operations. Whether delegating administrative privileges or managing application permissions, this cmdlet provides the flexibility and control needed for robust directory management.
For more detailed information and additional examples, refer to the official Microsoft documentation: New-MgDirectoryRoleMemberByRef
© m365corner.com. All Rights Reserved. Design by HTML Codex