New-MgGroupMember: How to Add Members to Microsoft 365 Groups

"This article provides a step-by-step guide to using New-MgGroupMember cmdlet in Graph PowerShell. Learn how to add single or multiple members to a group, troubleshoot common errors, and optimize bulk operations using CSV files."

The New-MgGroupMember cmdlet is part of the Microsoft Graph PowerShell module. It allows administrators to add a member to a Microsoft 365 group. This cmdlet is essential for managing group memberships in an automated and efficient manner.

Prerequisites

Before using the New-MgGroupMember cmdlet, ensure the following prerequisites are met:

• Microsoft Graph PowerShell Module: Install the Microsoft Graph PowerShell module if not already installed. You can do this using the command:

Install-Module Microsoft.Graph -Scope CurrentUser

• Authentication: Authenticate to Microsoft Graph using: Connect-MgGraph

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

• Group ID: Group Id to which member is to be added. The Group Id can be obtained using Get-MgGroup cmdlet.
• DirectoryObjectId (User Id): Id of the user to be added as member to group. The User Id can be obtained using Get-MgUser cmdlet.

Cmdlet Syntax

New-MgGroupMember -GroupId <String> -DirectoryObjectId <String> [<CommonParameters>]

Parameters:

• -GroupId: The unique identifier of the Microsoft 365 group to which the member will be added.
• -DirectoryObjectId: The unique identifier of the directory object (usually a user or service principal) to add to the group.
• <CommonParameters>: This cmdlet supports common parameters like -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, and -WarningAction. For more information see about_CommonParameters.

Usage Examples

Example 1: Add a user to a group

$groupId = "d9f6b5c5-67e5-41d1-9af0-8c85b6f15d0c"
$userId = "5c5d5f65-1d6b-4141-a5e5-b8c85d0c6e8f"
                                
try {
      New-MgGroupMember -GroupId $groupId -DirectoryObjectId $userId
      Write-Host "User with ID $userId has been successfully added to the group with ID $groupId." -ForegroundColor Green
} catch {
      Write-Host "Failed to add user to the group. Error: $_" -ForegroundColor Red
}

Example 2: Add multiple users to a group

$groupId = "d9f6b5c5-67e5-41d1-9af0-8c85b6f15d0c"
$userIds = @("5c5d5f65-1d6b-4141-a5e5-b8c85d0c6e8f", "6d7e8f70-6e7b-41d2-a6f7-9c85d7f16e9d")

foreach ($userId in $userIds) {
    try {
        New-MgGroupMember -GroupId $groupId -DirectoryObjectId $userId
        Write-Host "User with ID $userId successfully added to the group with ID $groupId." -ForegroundColor Green
    } catch {
        Write-Host "Failed to add user with ID $userId to the group. Error: $_" -ForegroundColor Red
    }
}

Example 3: Add members from a CSV file

To add members to a group from a CSV file, follow these steps:

Prepare the CSV File:

Ensure your CSV file (members.csv) contains headers like UserPrincipalName and GroupId. Here is an example of how your CSV file should look:

UserPrincipalName,GroupId
user1@domain.com,d9f6b5c5-67e5-41d1-9af0-8c85b6f15d0c
user2@domain.com,d9f6b5c5-67e5-41d1-9af0-8c85b6f15d0c

Import the CSV and Add Members:

$csvPath = "C:\path\to\your\members.csv"
$members = Import-Csv -Path $csvPath

foreach ($member in $members) {
    $user = Get-MgUser -UserPrincipalName $member.UserPrincipalName
    New-MgGroupMember -GroupId $member.GroupId -DirectoryObjectId $user.Id
}

Adding Group Members Using Admin Center

To add Group Members, select the group >> Membership tab >> Members tab >> Add Members >> select the user >> click Add button.

Cmdlet Tips

• Permissions: Ensure you have the necessary permissions to add members to a group. Typically, this requires Group Administrator or similar roles.
• Error Handling: Use -ErrorAction Stop to catch errors and handle them appropriately in your script.
• Bulk Operations: For adding multiple users, consider using loops or importing from a CSV file to streamline the process.
• Add multiple users in a loop or using a CSV file If you’re adding multiple users to a group, consider using a foreach loop or importing from a CSV. This ensures bulk operations are easier to manage and audit.

  $groupId = "GROUP_ID"
  Import-Csv "users.csv" | ForEach-Object {
      $userId = $_.UserId
      New-MgGroupMember -GroupId $groupId -DirectoryObjectId $userId
  }

• Ensure the user being added has a valid object ID and exists in the tenant
  Use Get-MgUser -UserId or Get-MgUser -Filter to confirm that the user exists and retrieve their Id. Passing an invalid or deleted user’s Id will throw an error.

Use Cases

1. Adding Multiple Users to Project Teams
• Scenario: When a new project team is formed, several users need to be added to a Microsoft 365 group to collaborate effectively.
• Implementation: Use New-MgGroupMember to bulk-add users to the project team group by looping through a list of user IDs or using a CSV file.
• Benefit: Streamlines the process of adding multiple users to a group, ensuring that the project team has access to all necessary resources immediately.


2. Granting Access to Security Groups:
• Scenario: : To enforce security policies or provide access to specific resources, users must be added to security groups.
• Implementation: Use New-MgGroupMember to quickly add users to these security groups, enabling access to applications, files, and other resources governed by group membership.
• Benefit: Ensures users have the right access based on their roles, improving security and compliance across the organization.


3. Automating Membership Updates for Dynamic Teams:
• Scenario: In a dynamic work environment, team memberships frequently change, requiring regular updates to group memberships.
• Implementation: Use New-MgGroupMember within automated scripts that run on a schedule, ensuring that group memberships are always up-to-date.
• Benefit: Automates the process of keeping group memberships current, reducing manual effort and ensuring that users have access to the correct resources based on real-time changes.


4. Managing Access for External Collaborators
• Scenario: External partners or vendors need temporary access to specific Microsoft 365 groups to collaborate on projects.
• Implementation: Use New-MgGroupMember to add external users to groups, with the option to set reminders for removing them after the project concludes.
• Benefit: Facilitates secure collaboration with external parties while ensuring their access is time-bound and properly managed.

Possible Errors & Solutions

Error: Invalid GroupId or DirectoryObjectId

Description: Resource 'GroupId' does not exist or one of its queried reference-property objects are not present.

Solution: Verify that the GroupId and DirectoryObjectId are correct and exist in your directory using Get-MgGroup and Get-MgUser cmdlets respectively.

Error: User Already Exists in Group

Description: Attempting to add a user who is already a member of the group results in an error.

Cause: The user is already a member, and duplicate additions are not allowed.

Solution: Check group membership before attempting to add the user using Get-MgGroupMember cmdlet:

    $existingMember = Get-MgGroupMember -GroupId $GroupId -UserId $UserId
    if (-not $existingMember) {
        New-MgGroupMember -GroupId $GroupId -UserId $UserId
    } else {
        Write-Output "User is already a member of the group."
    }

Error: Insufficient Privileges to Add Members

Description: You might encounter an error if your account lacks the necessary permissions to add members to a group.

Cause: The account used does not have sufficient administrative rights.

Solution: Ensure that your account has the "Group Administrator" or similar role that allows adding members to groups. Then reconnect using Connect-MgGraph

Frequently Asked Questions

• What is New-MgGroupMember?
  New-MgGroupMember is a Microsoft Graph PowerShell cmdlet that allows administrators to add users or service principals to a group in Microsoft 365. This cmdlet supports adding members to security groups and Microsoft Teams groups.
  
• Can I use New-MgGroupMember to add guest users to a group?
  Yes, you can use New-MgGroupMember to add guest users to a group. However, ensure the guest user is already added to the tenant, and you have their Object ID or UserPrincipalName for the operation.
• Can I use email addresses instead of object IDs to add members?
  No. The -DirectoryObjectId parameter strictly requires the Azure AD object ID of the user. You’ll need to resolve the user’s ID using a separate Get-MgUser call like:
  

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

• Does this cmdlet work for Microsoft 365 Groups and Security Groups?
  Yes. New-MgGroupMember can be used to add members to both Microsoft 365 Groups and Azure AD Security Groups. However, for Microsoft Teams, make sure the group is team-enabled, or use Add-MgTeamMember for role-specific membership (like owner/member).
• How to verify group membership after adding users to the group?
  Run Get-MgGroupMember -GroupId $groupId command. This should list the User Id of the user(s) you just added to the group.

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

Conclusion

The New-MgGroupMember cmdlet is a powerful tool for managing group memberships in Microsoft 365. By understanding its syntax, usage, and potential pitfalls, administrators can efficiently manage group memberships and automate related tasks. Whether you're handling day-to-day operations or implementing complex onboarding workflows, this cmdlet provides the functionality needed to keep your groups up-to-date and secure.

If You Prefer the Graph API Way

Note: To add members to a Microsoft 365 or security group using Graph API, send a POST request to /groups/{group-id}/members/$ref with the proper user reference (@odata.id) pointing to the user’s object URL.

Add a Single Member to a Group

# Replace with actual groupId and userId (GUIDs)
$groupId = "b320ca29-3775-4bb7-a0f8-e9abee3cdb2c"
$userId  = "2e539763-2706-464d-ba5a-8e94f1c552d5"
                                
# Define the user reference payload
$body = @{
 "@odata.id" = "https://graph.microsoft.com/v1.0/users/$userId"
}
                                
# Add the user to the group
Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/groups/$groupId/members/`$ref" -Body ($body | ConvertTo-Json)
                            

Bulk Add Members to a Group from CSV

# Sample CSV headers: userId
$groupId = "b320ca29-3775-4bb7-a0f8-e9abee3cdb2c"
$csvPath = "C:\Users\admin\Documents\group-members.csv"
                                
$users = Import-Csv -Path $csvPath

foreach ($user in $users) {
$body = @{
 "@odata.id" = "https://graph.microsoft.com/v1.0/users/$($user.userId)"
}
                                
$uri = "https://graph.microsoft.com/v1.0/groups/$groupId/members/`$ref"
Invoke-MgGraphRequest -Method POST -Uri $uri -Body ($body | ConvertTo-Json)
}
                            

CSV Format Example

userId
2e539763-2706-464d-ba5a-8e94f1c552d5
9a703db1-9ff8-4d60-bd64-4cceac69ad42
e0433c58-1d2f-4e5c-82cd-a111aa551c20

💡 The userId refers to the Azure AD Object ID of the user. Use Get-MgUser | Select Id, DisplayName to fetch them.

Required Permissions

To add members to groups using Graph API, you need:

• GroupMember.ReadWrite.All
• or Directory.ReadWrite.All

Graph API Documentation

Suggested Reading: