Microsoft Entra version 2 cmdlets for group management
This article contains examples of how to use PowerShell to manage your groups in Microsoft Entra ID, part of Microsoft Entra. It also tells you how to get set up with the Microsoft Graph PowerShell module. First, you must download the Microsoft Graph PowerShell module.
Install the Microsoft Graph PowerShell module
To install the MgGroup PowerShell module, use the following commands:
PS C:\Windows\system32> Install-module Microsoft.Graph
To verify that the module is ready to use, use the following command:
PS C:\Windows\system32> Get-Module -Name "*graph*"
ModuleType Version PreRelease Name ExportedCommands
---------- ------- ---------- ---- ----------------
Script 1.27.0 Microsoft.Graph.Authentication {Add-MgEnvironment, Connect-MgGraph, Disconnect-MgGraph, Get-MgContext…}
Script 1.27.0 Microsoft.Graph.Groups {Add-MgGroupDriveListContentTypeCopy, Add-MgGroupDriveListContentTypeCopyF…
Now you can start using the cmdlets in the module. For a full description of the cmdlets in the Microsoft Graph module, refer to the online reference documentation for Microsoft Graph PowerShell.
Connect to the directory
Before you can start managing groups using Microsoft Graph PowerShell cmdlets, you must connect your PowerShell session to the directory you want to manage. Use the following command:
PS C:\Windows\system32> Connect-MgGraph -Scopes "Group.ReadWrite.All"
The cmdlet prompts you for the credentials you want to use to access your directory. In this example, we're using karen@drumkit.onmicrosoft.com to access the demonstration directory. The cmdlet returns a confirmation to show the session was connected successfully to your directory:
Welcome To Microsoft Graph!
Now you can start using the MgGraph cmdlets to manage groups in your directory.
Retrieve groups
To retrieve existing groups from your directory, use the Get-MgGroups cmdlet.
To retrieve all groups in the directory, use the cmdlet without parameters:
PS C:\Windows\system32> Get-MgGroup -All
The cmdlet returns all groups in the connected directory.
You can use the -GroupId parameter to retrieve a specific group for which you specify the group’s objectID:
PS C:\Windows\system32> Get-MgGroup -GroupId 5e3eba05-6c2b-4555-9909-c08e997aab18 | fl
The cmdlet now returns the group whose objectID matches the value of the parameter you entered:
AcceptedSenders :
AllowExternalSenders :
AppRoleAssignments :
AssignedLabels :
AssignedLicenses :
AutoSubscribeNewMembers :
Calendar : Microsoft.Graph.PowerShell.Models.MicrosoftGraphCalendar
CalendarView :
Classification :
Conversations :
CreatedDateTime : 14-07-2023 14:25:49
CreatedOnBehalfOf : Microsoft.Graph.PowerShell.Models.MicrosoftGraphDirectoryObject
DeletedDateTime :
Description : Sales and Marketing
DisplayName : Sales and Marketing
Id : f76cbbb8-0581-4e01-a0d4-133d3ce9197f
IsArchived :
IsAssignableToRole :
IsSubscribedByMail :
LicenseProcessingState : Microsoft.Graph.PowerShell.Models.MicrosoftGraphLicenseProcessingState
Mail : SalesAndMarketing@M365x64647001.onmicrosoft.com
MailEnabled : True
MailNickname : SalesAndMarketing
RejectedSenders :
RenewedDateTime : 14-07-2023 14:25:49
SecurityEnabled : True
You can search for a specific group using the -filter parameter. This parameter takes an ODATA filter clause and returns all groups that match the filter, as in the following example:
PS C:\Windows\system32> Get-MgGroup -Filter "DisplayName eq 'Intune Administrators'"
DeletionTimeStamp :
ObjectId : aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
ObjectType : Group
Description : Intune Administrators
DirSyncEnabled :
DisplayName : Intune Administrators
LastDirSyncTime :
Mail :
MailEnabled : False
MailNickName : 4dd067a0-6515-4f23-968a-cc2ffc2eff5c
OnPremisesSecurityIdentifier :
ProvisioningErrors : {}
ProxyAddresses : {}
SecurityEnabled : True
Note
The MgGroup PowerShell cmdlets implement the OData query standard. For more information, see $filter in OData system query options using the OData endpoint.
Here you have an example that shows how to pull all groups that don't have an expiration policy applied
Connect-MgGraph -Scopes 'Group.Read.All'
Get-MgGroup -ConsistencyLevel eventual -Count groupCount -Filter "NOT (expirationDateTime+ge+1900-01-01T00:00:00Z)" | Format-List Id
This example does the same as the previous one, but the script also exports the results to CSV.
Connect-MgGraph -Scopes 'Group.Read.All'
Get-MgGroup -ConsistencyLevel eventual -Count groupCount -Filter "NOT (expirationDateTime+ge+1900-01-01T00:00:00Z)" | Format-List Id |Export-Csv -Path {path} -NoTypeInformation
This last example shows you how to retrieve only groups that belong to Teams
Get-MgGroup -ConsistencyLevel eventual -Count groupCount -Filter "NOT (expirationDateTime+ge+1900-01-01T00:00:00Z) and resourceProvisioningOptions/any(p:p eq 'Team')" | Format-List Id, expirationDateTime, resourceProvisioningOptions
Create groups
To create a new group in your directory, use the New-MgGroup cmdlet. This cmdlet creates a new security group called “Marketing":
$param = @{
description="My Demo Group"
displayName="DemoGroup"
mailEnabled=$false
securityEnabled=$true
mailNickname="Demo"
}
New-MgGroup @param
Update groups
To update an existing group, use the Update-MgGroup cmdlet. In this example, we’re changing the DisplayName property of the group “Intune Administrators.” First, we’re finding the group using the Get-MgGroup cmdlet and filter using the DisplayName attribute:
PS C:\Windows\system32> Get-MgGroup -Filter "DisplayName eq 'Intune Administrators'"
DeletionTimeStamp :
ObjectId : aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb
ObjectType : Group
Description : Intune Administrators
DirSyncEnabled :
DisplayName : Intune Administrators
LastDirSyncTime :
Mail :
MailEnabled : False
MailNickName : 4dd067a0-6515-4f23-968a-cc2ffc2eff5c
OnPremisesSecurityIdentifier :
ProvisioningErrors : {}
ProxyAddresses : {}
SecurityEnabled : True
Next, we’re changing the Description property to the new value “Intune Device Administrators”:
PS C:\Windows\system32> Update-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b -Description "Demo Group Updated"
Now, if we find the group again, we see the Description property is updated to reflect the new value:
PS C:\Windows\system32> Get-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b | select displayname, description
DisplayName Description
----------- -----------
DemoGroup Demo Group Updated
Delete groups
To delete groups from your directory, use the Remove-MgGroup cmdlet as follows:
PS C:\Windows\system32> Remove-MgGroup -GroupId 958d212c-14b0-43d0-a052-d0c2bb555b8b
Manage group membership
Add members
To add new members to a group, use the New-MgGroupMember cmdlet. This command adds a member to the Intune Administrators group we used in the previous example:
PS C:\Windows\system32> New-MgGroupMember -GroupId f76cbbb8-0581-4e01-a0d4-133d3ce9197f -DirectoryObjectId a88762b7-ce17-40e9-b417-0add1848eb68
The -GroupId parameter is the ObjectID of the group to which we want to add a member, and the -DirectoryObjectId is the ObjectID of the user we want to add as a member to the group.
Get members
To get the existing members of a group, use the Get-MgGroupMember cmdlet, as in this example:
PS C:\Windows\system32> Get-MgGroupMember -GroupId 2c52c779-8587-48c5-9d4a-c474f2a66cf4
Id DeletedDateTime
-- ---------------
aaaaaaaa-bbbb-cccc-1111-222222222222
bbbbbbbb-cccc-dddd-2222-333333333333
Remove members
To remove the member we previously added to the group, use the Remove-MgGroupMember cmdlet, as is shown here:
PS C:\Windows\system32> Remove-MgGroupMemberByRef -DirectoryObjectId 00aa00aa-bb11-cc22-dd33-44ee44ee44ee -GroupId 2c52c779-8587-48c5-9d4a-c474f2a66cf4
Verify members
To verify the group memberships of a user, use the Select-MgGroupIdsUserIsMemberOf cmdlet. This cmdlet takes as its parameters the ObjectId of the user for which to check the group memberships, and a list of groups for which to check the memberships. The list of groups must be provided in the form of a complex variable of type “Microsoft.Open.AzureAD.Model.GroupIdsForMembershipCheck”, so we first must create a variable with that type:
Get-MgUserMemberOf -UserId 00aa00aa-bb11-cc22-dd33-44ee44ee44ee
Id DisplayName Description GroupTypes AccessType
-- ----------- ----------- ---------- ----------
5dc16449-3420-4ad5-9634-49cd04eceba0 demogroup demogroup {Unified}
The value returned is a list of groups of which this user is a member. You can also apply this method to check Contacts, Groups or Service Principals membership for a given list of groups, using Select-MgGroupIdsContactIsMemberOf, Select-MgGroupIdsGroupIsMemberOf or Select-MgGroupIdsServicePrincipalIsMemberOf
Disable group creation by your users
You can prevent non-admin users from creating security groups. The default behavior in Microsoft Online Directory Services (MSODS) is to allow non-admin users to create groups, whether or not self-service group management (SSGM) is also enabled. The SSGM setting controls behavior only in the My Groups portal.
To disable group creation for non-admin users:
Verify that non-admin users are allowed to create groups:
PS C:\> Get-MgBetaDirectorySetting | select -ExpandProperty values Name Value ---- ----- NewUnifiedGroupWritebackDefault true EnableMIPLabels false CustomBlockedWordsList EnableMSStandardBlockedWords false ClassificationDescriptions DefaultClassification PrefixSuffixNamingRequirement AllowGuestsToBeGroupOwner false AllowGuestsToAccessGroups true GuestUsageGuidelinesUrl GroupCreationAllowedGroupId AllowToAddGuests true UsageGuidelinesUrl ClassificationList EnableGroupCreation trueIf it returns
EnableGroupCreation : True, then non-admin users can create groups. To disable this feature:Install-Module Microsoft.Graph.Beta.Identity.DirectoryManagement Import-Module Microsoft.Graph.Beta.Identity.DirectoryManagement $params = @{ TemplateId = "62375ab9-6b52-47ed-826b-58e47e0e304b" Values = @( @{ Name = "EnableGroupCreation" Value = "false" } ) } Connect-MgGraph -Scopes "Directory.ReadWrite.All" New-MgBetaDirectorySetting -BodyParameter $params
Manage owners of groups
To add owners to a group, use the New-MgGroupOwner cmdlet:
PS C:\Windows\system32> New-MgGroupOwner -GroupId 0e48dc96-3bff-4fe1-8939-4cd680163497 -DirectoryObjectId 92a0dad0-7c9e-472f-b2a3-0fe2c9a02867
The -GroupId parameter is the ObjectID of the group to which we want to add an owner, and the -DirectoryObjectId is the ObjectID of the user or service principal we want to add as an owner.
To retrieve the owners of a group, use the Get-MgGroupOwner cmdlet:
PS C:\Windows\system32> Get-MgGroupOwner -GroupId 0e48dc96-3bff-4fe1-8939-4cd680163497
The cmdlet returns the list of owners (users and service principals) for the specified group:
Id DeletedDateTime
-- ---------------
8ee754e0-743e-4231-ace4-c28d20cf2841
85b1df54-e5c0-4cfd-a20b-8bc1a2ca7865
4451b332-2294-4dcf-a214-6cc805016c50
If you want to remove an owner from a group, use the Remove-MgGroupOwnerByRef cmdlet:
PS C:\Windows\system32> Remove-MgGroupOwnerByRef -GroupId 0e48dc96-3bff-4fe1-8939-4cd680163497 -DirectoryObjectId 92a0dad0-7c9e-472f-b2a3-0fe2c9a02867
Reserved aliases
When a group is created, certain endpoints allow the end user to specify a mailNickname or alias to be used as part of the email address of the group. Groups with the following highly privileged email aliases can only be created by a Microsoft Entra Global Administrator.
- abuse
- admin
- administrator
- hostmaster
- majordomo
- postmaster
- root
- secure
- security
- ssl-admin
- webmaster
Group writeback to on-premises
Today, many groups are still managed in on-premises Active Directory. To answer requests to sync cloud groups back to on-premises, the groups writeback feature for Microsoft Entra ID using Microsoft Entra cloud sync is now available.
Important
The public preview of Group Writeback v2 in Microsoft Entra Connect Sync will no longer be available after June 30, 2024. This feature will be discontinued on this date, and you will no longer be supported in Connect Sync to provision cloud security groups to Active Directory. The feature will continue to operate beyond the discontinuation date; however, it will no longer receive support after this date and may cease functioning at any time without notice.
We offer similar functionality in Microsoft Entra Cloud Sync called Group Provision to Active Directory that you can use instead of Group Writeback v2 for provisioning cloud security groups to Active Directory. We're working on enhancing this functionality in Cloud Sync along with other new features that we're developing in Cloud Sync.
Customers who use this preview feature in Connect Sync should switch their configuration from Connect Sync to Cloud Sync. You can choose to move all your hybrid sync to Cloud Sync (if it supports your needs). You can also run Cloud Sync side by side and move only cloud security group provisioning to Active Directory onto Cloud Sync.
For customers who provision Microsoft 365 groups to Active Directory, you can keep using Group Writeback v1 for this capability.
You can evaluate moving exclusively to Cloud Sync by using the user synchronization wizard.
Next steps
You can find more Azure Active Directory PowerShell documentation at Microsoft Entra Cmdlets.