Table of Contents
Managing Group Membership is a Very Common Administrative Operation
Browsing through the set of open issues for the Microsoft Graph PowerShell SDK (as you do), I came upon issue #3751 which reports that the documentation doesn’t contain an example for the New-MgGroupMember cmdlet. Given that adding members to Entra ID groups is a very common administrative operation, it seemed strange not to have any documentation.
Two Cmdlets to Do One Job
New-MgGroupMember is an interesting cmdlet because from a practical perspective, it achieves the same result as the New-MgGroupMemberByRef cmdlet. Both cmdlets add a new member to Entra ID groups with static membership where membership is managed in the cloud. The membership of a dynamic group can only be changed by modifying the membership rule for the group.
The obvious question is why the Microsoft Graph PowerShell SDK includes two cmdlets to do the same job. It’s because Microsoft generates the SDK cmdlets from Graph metadata, and the metadata for group members exposes two distinct operations:
- Update the members navigation property (New-MgGroupMember).
- Manage references through the members $ref endpoint (New-MgGroupMemberByRef).
Group owners use the same structure, which is why the New-MgGroupOwner and New-MgGroupOwnerByRef cmdlets exist.
This command uses the New-MgGroupMember cmdlet to add a new group member. You must use the object identifier for the new member. Other values like an account’s user principal name cannot be used to identify an object:
$UserId = Get-MgUser -Filter "displayName eq 'Adele Vance'" | Select-Object -ExpandProperty Id $GroupId = Get-MgGroup -Filter "displayname eq 'Microsoft Graph PowerShell SDK Gurus'" | Select-Object -ExpandProperty Id New-MgGroupMember -GroupId $GroupId -DirectoryObjectId $UserId
Exactly the same result is achieved by running the New-MgGroupMemberByRef cmdlet, albeit with some additional setup to create the request body to define the new member:
$MemberRef = ("https://graph.microsoft.com/v1.0/directoryObjects/{0}" -f $UserId)
$MemberInfo = @{}
$MemberInfo.Add("@odata.id", $MemberRef)
The request body looks like this:
$MemberInfo Name Value ---- ----- @odata.id https://graph.microsoft.com/v1.0/directoryObjects/8cc6726c-dee2-4059-9bde-44e3173af025
And is consumed by the cmdlet like this:
New-MgGroupMemberByRef -GroupId $GroupId -BodyParameter $MemberInfo
Some might assume that because Microsoft uses New-MgGroupMemberByRef in the Graph documentation for adding a member to a group, it’s the preferred approach. That’s not true. The New-MgGroupMember cmdlet is easier to work with, which is why it is sometimes called a convenience cmdlet because the SDK does the work for you to build the necessary input object. I recommend that you use New-MgGroupMember whenever possible.
Although Microsoft 365 Groups only support user accounts (including guests) as members, security groups support other object types such as other groups, devices, and service principals. In all cases, the identifier is sufficient to tell the Graph which object you want to add to a group.
Member References
Within groups, members and owners are defined as relationships or references to other directory objects (backlinks in Active Directory terms). The Graph exposes dedicated $ref endpoints to manage those relationships to make it easy to find, manage, and list the references (Figure 1). The build process for the Graph SDK detects the presence of the $ref endpoints and creates cmdlets to add and remove membership relationships.
Interestingly, while the Remove-MgGroupMemberByRef cmdlet is available to remove a member from a group, the SDK doesn’t contain a Remove-MgGroupMember cmdlet. The Graph API removes group members through the $ref relationship endpoint, so the SDK only exposes the reference-based removal cmdlet. The same is true for owners, where Remove-MgGroupOwnerByRef must be used to remove an owner from a group.
No Exchange Objects
The New-MgGroupMember and New-MgGroupMemberByRef cmdlets cannot be used to add members to distribution groups and mail-enabled security groups. Exchange Online rather than Entra ID exerts control over these objects, and membership changes must be processed using Exchange cmdlets like Add-DistributionGroupMember.
Closing the Loop
I’ve submitted a pull request to add a simple example of how to use the New-MgGroupMember cmdlet. The Graph SDK is still hosted in a public repository. Unlike Microsoft’s plan to make many documentation repositories private, it’s possible for external people to propose changes to documentation. However, the Graph SDK documentation is generated from the SDK source and Graph metadata, which is different to normal Microsoft Learn articles. We’ll see whether Microsoft accepts my pull request. It’s a small example of how community contributions can improve documentation quality. Whether that model survives Microsoft’s move away from public documentation repositories remains to be seen.
Need help to write and manage PowerShell scripts for Microsoft 365, including Azure Automation runbooks? Get a copy of the Automating Microsoft 365 with PowerShell eBook, available standalone or as part of the Microsoft 365 for IT Pros eBook bundle.