How to Use New-MgGroupMemberByRef to Add Microsoft 365 Group Members?

Adding users to Microsoft 365 groups is a common task for IT administrators. While the Microsoft 365 admin portal allows for manual group management, PowerShell provides a faster, repeatable, and scalable way to handle group membership—especially when dealing with multiple users.

In this article, we’ll walk you through how to use the New-MgGroupMemberByRef cmdlet to add members to Microsoft 365 groups efficiently using Microsoft Graph PowerShell.

What is New-MgGroupMemberByRef?

New-MgGroupMemberByRef is a Microsoft Graph PowerShell cmdlet that allows you to add a member to a Microsoft 365 Group by referencing the user's directory object ID (GUID).

Instead of using email addresses or display names, this cmdlet uses a specific object reference URL, making it accurate and script-friendly for automation tasks.

Why Use New-MgGroupMemberByRef?

Here are a few reasons why admins choose this method:

• Bulk user additions made easy
• Works great with automation and CSV imports
• Avoids issues caused by duplicate display names or aliases
• Ensures precision by using object IDs (GUIDs)

Cmdlet Syntax

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

Parameters:

• -GroupId: The unique identifier (GUID) of the Microsoft 365 Group.
• -BodyParameter: A hashtable that contains the @odata.id property pointing to the directory object of the user being added.

Usage Examples

Single Member Addition

$NewMember = @{
    "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/12345678-90ab-cdef-1234-567890abcdef"
}
                                        
New-MgGroupMemberByRef -GroupId "87654321-fedc-ba98-7654-3210fedcba98" -BodyParameter $NewMember
                                        

Multiple Member Additions

$Members = @(
    @{
        "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/12345678-90ab-cdef-1234-567890abcdef"      
    },
    @{
        "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/23456789-0abc-def1-2345-67890abcdef1"
    }
)
                                        
foreach ($Member in $Members) {
    New-MgGroupMemberByRef -GroupId "87654321-fedc-ba98-7654-3210fedcba98" -BodyParameter $Member
}
                                        

Bulk Import by Reading Data from a CSV File

$GroupId = "87654321-fedc-ba98-7654-3210fedcba98"
$CsvPath = "C:\Path\To\Users.csv"
$Users = Import-Csv -Path $CsvPath
                                            
foreach ($User in $Users) {
    $NewMember = @{
        "@odata.id" = "https://graph.microsoft.com/v1.0/directoryObjects/$($User.UserId)"
    }
    New-MgGroupMemberByRef -GroupId $GroupId -BodyParameter $NewMember
}
                                        

Sample CSV Format

UserId
12345678-90ab-cdef-1234-567890abcdef
23456789-0abc-def1-2345-67890abcdef1

Frequently Asked Questions

Can I use email addresses instead of UserId?

No, this cmdlet requires the directory object ID of the user. If you only have the email, you can retrieve the ID using:

(Get-MgUser -UserPrincipalName "user@domain.com").Id

Will this also add the user to a Microsoft Team?

Yes! If the Microsoft 365 Group is backed by a Team, adding the user to the group will make them a member of the Team as well.

What permissions are required?

You'll need Group.ReadWrite.All permission when connecting with Connect-MgGraph. Admin consent is required.

Use Cases

Here are some practical scenarios for using New-MgGroupMemberByRef:

1. Automated User Onboarding: Add new hires to department or project groups automatically.
2. Bulk Group Membership Management: Quickly reassign users across multiple groups during reorganizations.
3. Access Control: Script-based access provisioning in compliance with organizational policies.
4. CSV-Based Imports: Load group members from HR systems or Excel lists for batch processing.

Conclusion

The New-MgGroupMemberByRef cmdlet is a powerful, precise, and scalable tool for adding members to Microsoft 365 Groups using Graph PowerShell. Whether you're working with a single user, multiple members, or importing from CSV, this cmdlet fits perfectly into your IT automation toolkit.

Take control of your group membership tasks and streamline user provisioning—all from your PowerShell console.