New-MgGroupMemberByRef: How to Add Members by Reference to Microsoft 365 Groups

This guide provides an in-depth look at the New-MgGroupMemberByRef cmdlet in Microsoft Graph PowerShell. Learn how to efficiently add members to Microsoft 365 groups using the reference-based approach, ideal for bulk operations and advanced scenarios.

The New-MgGroupMemberByRef cmdlet is a powerful tool within the Microsoft Graph PowerShell module that allows administrators to add members to a Microsoft 365 group by referencing their directory objects. This cmdlet is particularly useful for bulk additions, streamlining group management tasks, and integrating with automated scripts.

Cmdlet Syntax

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

Parameters:
-GroupId: The unique identifier (ID) of the group where the members will be added.
-BodyParameter: A hashtable containing the necessary properties to reference the users being added.

Usage Examples

1. Adding a Single Member to a Group:

To add a single user to a group, you can use the following example:

$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

This example adds a user with the ID 12345678-90ab-cdef-1234-567890abcdef to the group with the ID 87654321-fedc-ba98-7654-3210fedcba98.

2. Adding Multiple Members to a Group:

For adding multiple members, you can create a list of users and iterate through them:

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

This script adds two users to the specified group.

3. Importing Members from a CSV File:

For large-scale operations, importing members from a CSV file can be highly efficient. Here’s how:

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.

Checking for the Newly Added Group Members

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

Cmdlet Tips

• Consistency Matters: Ensure the @odata.id property is correctly formatted, as even minor errors can cause the cmdlet to fail.
• Batch Processing: When adding a large number of members, consider using batch requests to improve efficiency.
• Error Handling: Implement error handling in your scripts to manage scenarios where a user might already be a member of the group.

Use Cases

• Automated User Management:
  Automating group membership management with New-MgGroupMemberByRef is ideal for scenarios where users need to be added to groups based on their role, department, or project. This cmdlet can be incorporated into scripts that run daily or weekly to ensure group memberships are always up to date.
• Bulk Onboarding:
  During the onboarding process of new employees, adding them to the appropriate groups (e.g., department-specific groups) is critical. This cmdlet can be used in conjunction with a CSV file that HR provides, ensuring new hires are quickly integrated into the necessary communication channels.
• Project-Based Group Management:
  For companies managing multiple projects, New-MgGroupMemberByRef can be used to quickly assemble project teams by adding members from different departments to a dedicated group, facilitating seamless collaboration.

Differences Between New-MgGroupMemberByRef and New-MgGroupMember Cmdlets

1. Method of Adding Members:
• New-MgGroupMemberByRef: This cmdlet adds members by referencing their directory objects using the @odata.id property. It is particularly useful when working with large datasets or when the directory object IDs are readily available.
• New-MgGroupMember: This cmdlet adds members by directly providing the user's properties, such as userPrincipalName or ObjectId. It’s straightforward but may require additional lookups if you only have partial user details.
2. Flexibility in Bulk Operations:
• New-MgGroupMemberByRef: Ideal for bulk operations, especially when adding members from external systems where directory object IDs are available. The -BodyParameter can be easily generated and iterated over in scripts.
• New-MgGroupMember: While capable of bulk operations, it’s more suited for scenarios where user details like email addresses or user principal names are directly known.
3. Complexity:
• New-MgGroupMemberByRef: Slightly more complex due to the requirement of formatting the @odata.id correctly, but it provides a more powerful and flexible approach for automation scripts.
• New-MgGroupMember: Easier to use for simple, direct additions of users, especially when integrating with other scripts or tools that directly provide user details.
4. Use Cases:
• New-MgGroupMemberByRef: Best suited for integration with automation workflows, large-scale user management, and scenarios where directory object IDs are used across systems.
• New-MgGroupMember: Ideal for simpler tasks, one-off additions, or scenarios where user details are directly accessible.

Possible Errors & Solutions

Frequently Asked Questions

• What is New-MgGroupMemberByRef used for?
  New-MgGroupMemberByRef is a Microsoft Graph PowerShell cmdlet used to add members to Microsoft 365 groups by referencing their directory object IDs. It’s suitable for advanced use cases, such as automating bulk member additions.
• How does New-MgGroupMemberByRef differ from New-MgGroupMember?
  The key difference lies in the method of adding members. While New-MgGroupMember requires the direct Object ID or UserPrincipalName, New-MgGroupMemberByRef allows referencing objects via their resource URLs, making it better suited for scenarios involving external or service accounts.
• How can I bulk add members using New-MgGroupMemberByRef?
  To bulk add members, prepare a CSV file with the following columns:

  
  GroupId,MemberReference
  <YourGroupId1>,https://graph.microsoft.com/v1.0/directoryObjects/<ObjectId1>
  <YourGroupId2>,https://graph.microsoft.com/v1.0/directoryObjects/<ObjectId2>

  Here’s the PowerShell script to process the CSV and add members to their respective groups:

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

"https://graph.microsoft.com/v1.0/directoryObjects/{ObjectId}"

Conclusion

The New-MgGroupMemberByRef cmdlet is a versatile tool for managing group memberships in Microsoft 365. Whether adding single users, multiple users, or importing users from a CSV file, this cmdlet simplifies the process and can be easily integrated into your automation scripts. By understanding the differences between New-MgGroupMemberByRef and New-MgGroupMember, you can choose the most appropriate cmdlet for your needs, ensuring efficient and effective group management in your organization.

Suggested Reading: