M365 PowerShell

How to Use New-MgGroupOwnerByRef in Graph PowerShell

This guide explains how to use the New-MgGroupOwnerByRef cmdlet in Microsoft Graph PowerShell to assign owners to Microsoft 365 groups. Learn to add single or multiple owners with practical examples for efficient group management.

Managing group ownership in Microsoft 365 is crucial for ensuring proper administration and security. The New-MgGroupOwnerByRef cmdlet allows administrators to add owners to a Microsoft 365 group programmatically. This article will guide you through the usage of this cmdlet, covering syntax examples, cmdlet tips, and a detailed comparison with the New-MgGroupOwner cmdlet.

Cmdlet Syntax

New-MgGroupOwnerByRef -GroupId <String> -BodyParameter <Hashtable>

Parameters:
-GroupId: The unique identifier (ID) of the group.
-BodyParameter: A hashtable containing the owner information. This parameter follows strict conventions as detailed in the Microsoft documentation.

Usage Examples

Adding a Single Owner

$Owner = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/users/{UserId}"
}
New-MgGroupOwnerByRef -GroupId "5c67f5b3-b1c4-4c16-842d-11b453b6f270" -BodyParameter $Owner

Explanation: This command adds a single owner to the specified group. Replace {UserId} with the actual ID of the user you want to add as an owner.

Adding Multiple Owners

$Owners = @(
    @{
        "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/2017e571-90fd-4671-96bb-360c678f4d23"
    }
    @{
        "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/55bafc67-7ba0-4964-840a-53d480542ab8"
    }
)

foreach ($Owner in $Owners) {
    New-MgGroupOwnerByRef -GroupId "3a408d7b-d2d1-4ec6-812f-b9ad64187a13" -BodyParameter $Owner
}

Explanation: This example shows how to add multiple owners to a group by looping through the owner data and passing each one to the -BodyParameter.

Importing Owners from a CSV

$OwnersFromCSV = Import-Csv -Path "C:\Path\To\Owners.csv"
foreach ($Owner in $OwnersFromCSV) {
    $OwnerHash = @{
        "@odata.id" = "https://graph.microsoft.com/v1.0/users/$($Owner.UserId)"
    }
    New-MgGroupOwnerByRef -GroupId "5c67f5b3-b1c4-4c16-842d-11b453b6f270" -BodyParameter $OwnerHash
}

Explanation: This script imports owner information from a CSV file and adds each owner to the specified group by looping through the imported data and passing each owner’s details to the -BodyParameter.

Checking for the Newly Added Group Owners

Execute Get-MgGroupOwner and provide the Group-Id. The newly added users will get listed.

Cmdlet Tips

Follow MSFT Documentation: Always ensure that the -BodyParameter hashtable is constructed as per Microsoft’s documentation to avoid errors. Incorrect formatting or missing keys can lead to failed operations.
Bulk Operations: For large groups, consider using bulk operations with the CSV method to streamline the process.
Permissions: Ensure that you have sufficient permissions to add owners to groups as this cmdlet requires administrative privileges.

Possible Errors & Solutions

"The If-Match header must be specified for this kind of request. Status: 412 (PreconditionFailed)"

Cause: The request requires an If-Match header to specify the version of the object being modified.

Solution: Ensure that you are passing the correct headers. If working with the New-MgGroupOwnerByRef cmdlet, ensure that you are following the conventions and not trying to update an existing owner improperly.

"Request_UnsupportedQuery"

Cause: An unsupported query is being used in the request.

Solution: Double-check the parameters and ensure that you are not using unsupported filters or query options. Stick to the basics as provided in the MSFT documentation.

"BadRequest - Invalid URL"

Cause: The URL in the @odata.id field is incorrectly formatted.

Solution: Ensure the @odata.id is correctly pointing to a valid user URL in the format "https://graph.microsoft.com/v1.0/users/{UserId}".

Use Cases

Delegated Administration: Use this cmdlet to quickly assign group ownership to multiple administrators, ensuring they have the necessary permissions to manage group settings and membership.
Onboarding New Admins: When onboarding new administrators, use the CSV import method to bulk assign them as owners to relevant groups. This can streamline the onboarding process and ensure that all necessary groups are properly managed.
Security Compliance: Ensure that all critical groups have at least two owners to comply with security best practices. This cmdlet can be used to audit and add additional owners where necessary.

Comparison: New-MgGroupOwnerByRef vs. New-MgGroupOwner

Parameter Usage: New-MgGroupOwnerByRef uses the -BodyParameter to pass owner information in a hashtable adhering strictly to the @odata.id format. New-MgGroupOwner directly accepts parameters such as -GroupId and -UserId, making it more straightforward for single user operations.
Flexibility: New-MgGroupOwnerByRef provides more flexibility for complex scenarios such as bulk additions and passing multiple owners by utilizing a hashtable. New-MgGroupOwner is simpler and more suited for straightforward use cases.
Error Handling: New-MgGroupOwnerByRef requires careful construction of the BodyParameter to avoid errors, making it slightly more error-prone but powerful in advanced scenarios. New-MgGroupOwner has less potential for errors due to its simpler parameter structure.

Frequently Asked Questions

What is New-MgGroupOwnerByRef used for?

New-MgGroupOwnerByRef is a Microsoft Graph PowerShell cmdlet used to assign owners to Microsoft 365 groups by referencing their directory object IDs.

How can I assign a single owner to a group?

You can assign a single owner to a group using the following script:

$Body = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/<OwnerObjectId>"
}
New-MgGroupOwnerByRef -GroupId "<GroupId>" -BodyParameter $Body

Can I assign multiple owners to a group using a CSV file?

Yes, prepare a CSV file with the following format:

GroupId,OwnerReference
<YourGroupId1>,https://graph.microsoft.com/v1.0/directoryObjects/<ObjectId1>
<YourGroupId27gt;,https://graph.microsoft.com/v1.0/directoryObjects/<ObjectId2>

$Data = Import-Csv -Path "C:\Path\To\File.csv"
foreach ($Row in $Data) {
    $Body = @{
        "@odata.id" = $Row.OwnerReference
    }
New-MgGroupOwnerByRef -GroupId $Row.GroupId -BodyParameter $Body
}

What permissions are required to assign group owners?

You need the following permissions to assign group owners:

Delegated Permissions: Group.ReadWrite.All
Application Permissions: GroupMember.ReadWrite.All

Conclusion

The New-MgGroupOwnerByRef cmdlet is a powerful tool for managing group ownership in Microsoft 365, especially in complex scenarios requiring bulk additions or CSV imports. While it offers flexibility and power, it requires careful adherence to Microsoft’s documentation to avoid common errors. By understanding its proper usage and potential pitfalls, administrators can effectively leverage this cmdlet to streamline group management processes and ensure compliance with organizational policies.

Additional Resources:

Graph PowerShell New-MgGroupOwnerByRef Cmdlet Documentation
Microsoft Graph PowerShell Module Documentation
Microsoft Graph API Documentation