Using New-MgDirectoryRoleMemberByRef in Graph PowerShell

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.


Prerequisites

  • Microsoft Graph PowerShell Module: Ensure you have the Microsoft Graph PowerShell module installed. You can install it using the following command:
    Install-Module Microsoft.Graph -Scope CurrentUser
  • Permissions: You need the appropriate permissions to execute the New-MgApplication cmdlet. The required Graph API permission is: RoleManagement.ReadWrite.Directory

Cmdlet Syntax

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.

Usage Examples

Example 1: Adding a User to a Directory Role

$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.

Example 2: Adding a Service Principal to a Directory Role

$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.


Cmdlet Tips

  • Role Identification: Use the Get-MgDirectoryRole cmdlet to identify roles by their display name. This helps in ensuring you are adding members to the correct role.
  • Member Identification: Utilize Get-MgUser for users and Get-MgServicePrincipal for service principals to get their IDs. This is crucial for accurate member addition.
  • Error Handling: Use common parameters like -ErrorAction and -Verbose to manage errors and get detailed output for troubleshooting.

Use Cases

  • Delegating Administrative Privileges: Assigning specific users or service principals to roles like Global Administrator or User Administrator.
  • Application Management: Adding service principals to roles like Application Administrator to manage app permissions and configurations.
  • Security and Compliance: Ensuring that only authorized personnel are assigned to sensitive roles within the organization.

Possible Errors & Solutions

Error: "Resource not found"

Cause: This typically occurs if the specified role or user/service principal ID does not exist.

Solution:

  • Verify the role ID and user/service principal ID.
  • Use Get-MgDirectoryRole and Get-MgUser or Get-MgServicePrincipal to confirm the existence of these IDs.

Error: "Insufficient privileges to complete the operation"

Cause: The executing account does not have the necessary permissions.

Solution:

  • Ensure that the executing account has sufficient privileges to manage directory roles.
  • Consider using a Global Administrator account or one with the necessary directory role permissions.

Conclusion

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


Related Articles:

Using Get-MgDirectoryRole in Graph PowerShell
Using Get-MgUserLicenseDetail in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Connect to Microsoft 365 Using PowerShell
How to Create Bulk Users in Office 365 Using Graph PowerShell?
Create Microsoft 365 Group Using Microsoft Graph PowerShell
Block Microsoft 365 User Using Microsoft Graph PowerShell
Assign Microsoft 365 License Using Graph PowerShell
Microsoft 365 User Management Using Graph PowerShell
Checking Group Membership in Microsoft 365
Bulk Assign Microsoft 365 License
Find Inactive Users in Microsoft 365
Using Powershell Graph Search Query
Using Powershell Graph Filter Query
Using Where-Object In Graph PowerShell
Using Expand Property In Graph PowerShell
Using Select Object In Graph PowerShell
Using -Contains Operator In Graph PowerShell
Add User to Multiple Microsoft 365 Groups Using Graph PowerShell
Get Microsoft 365 User Location Using Graph PowerShell
Import Microsoft 365 Groups from CSV File Using Graph PowerShell
Microsoft 365 Group User Import Using Graph PowerShell

© m365corner.com. All Rights Reserved. Design by HTML Codex