New-MgGroupMemberByRef

What is New-MgGroupMemberByRef?

New-MgGroupMemberByRef is a Microsoft Graph PowerShell cmdlet used to add directory objects (typically users) as members of a Microsoft 365 or security group by reference. It posts the member’s object ID to the group’s members collection.

Why Use New-MgGroupMemberByRef?

Admins use this cmdlet to automate group membership management at scale. It’s ideal for bulk onboarding, project-based access changes, licensing workflows, and scheduled audits—without manual clicks in the admin center. Because it works with object references, it’s fast, script-friendly, and dependable for large tenants.

Prerequisites

Make sure you’re connected to Graph with write permissions for groups:

• Install Microsoft Graph module (if needed):
  

  Install-Module Microsoft.Graph -Scope CurrentUser

• Connect with the right scope:
  

  Connect-MgGraph -Scopes "Group.ReadWrite.All" 

How to use New-MgGroupMemberByRef?

Basic syntax:

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

You pass the target GroupId and a hashtable containing the member’s @odata.id (directoryObject URL). Use it for single additions, loops, or CSV-driven bulk updates.

New-MgGroupMemberByRef Examples

• Example 1: Adding a Single Member to a Group:

$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
                                            

• Example 2: Adding Multiple Members to a Group:

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

• Example 3: Importing Members from a CSV File:

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

PowerShell Script:

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

This script imports user IDs from a CSV file and adds them to the specified group.

Summary

Key Point	Details
Cmdlet Name	New-MgGroupMemberByRef
Purpose	Adds a user/object to a Microsoft 365 or security group
Required Scope	Group.ReadWrite.All
Primary Parameters	GroupId, BodyParameter
Automation Benefit	Bulk membership changes via loops/CSV without Admin Center
Use Case	Onboarding, project access provisioning, mass group updates