In this tutorial, I am going to walk you through how to create Groups in Azure Active Directory using Microsoft Graph PowerShell. We will look at the different methods of creating groups and any quirks around the available parameters.
About New-MgGroup
- Module: Microsoft.Graph.Groups
- Minimum permissions: Group.ReadWrite.All
The New-MgGroup enables you to create new groups in your Microsoft 365 tenant as defined in the request body. A complete list of group parameters can be found in the reference documentation here or you can run the following command in PowerShell.
(Get-Command New-MgGroup).ParametersSimilar to the above, you can also view a list of all permission which pertain to the New-MgGroup cmdlet with the following command.
(Find-MgGraphCommand -Command New-MgGroup).PermissionsThere are also two different methods to creating a group with this cmdlet. You can either use the available parameters to define the settings for your group, such as -DisplayName, -MailNickName etc… or you can include all information within a hashtable and use -BodyParameter. Both options I will cover in this tutorial.
Supported group types with Microsoft Graph PowerShell
As Microsoft Graph has limited access to Exchange, currently the only supported group types you can create with Microsoft Graph PowerShell are Microsoft 365 groups and Security groups.
This means that you are unable to use Microsoft Graph PowerShell to create Distribution groups or mail-enabled security groups. It is also true that you cannot create mail-enabled Microsoft 365 groups either.
If you do try to create a mail-enabled group, you will be greeted with the following error:
New-MgGroup : Cannot Create a mail-enabled security groups and or distribution list.
To fix the error you must ensure your -MailEnabled parameter is set to $false.
How to create groups with Microsoft Graph PowerShell
To create a simple group you can use the below example, which will create a Security group:
New-MgGroup -DisplayName 'MySecurityGroup' `
-MailEnabled:$False `
-MailNickName 'MySecurityGroup' `
-SecurityEnabledYou can see from the above that you are still required to define the -MailEnabled parameter with a value of $false, even though it is not supported.
The below example is that of a more complex configuration, here I have created a dynamic security group. For this, I have included some additional parameters, including:
- -GroupTypes – To define the group type as a dynamic group.
- -MemberShipRule – To define the membership rule of which members will be added.
- -MembershipRuleProcessingState – To turn rule processing on.
New-MgGroup -DisplayName 'MyDynSecurityGroup' `
-MailEnabled:$False `
-MailNickName 'MyDynSecurityGroup' `
-SecurityEnabled `
-GroupTypes DynamicMembership `
-MembershipRule '(user.userPrincipalName -contains "ourcloudnetwork.com") and (user.accountEnabled -eq True)' `
-MembershipRuleProcessingState OnThe -GroupTypes parameter also allows us to create either a standard security group or a Microsoft 365 group. It can also include more than one value, for example, the below command will create a Microsoft 365 group with dynamic membership.
New-MgGroup -DisplayName 'MyDynM365Group' `
-MailEnabled:$False `
-MailNickName 'MyDynM365Group' `
-SecurityEnabled `
-GroupTypes DynamicMembership,Unified `
-MembershipRule '(user.userPrincipalName -contains "ourcloudnetwork.com")' `
-MembershipRuleProcessingState OnHow to create groups with the -body parameter
You can also achieve the same result when creating groups by using the -bodyparameter parameter.
To do this you will need to create a hashtable @{} which contains all the values for your group. Let’s use the last example in the above section and create the same group by defining the settings in a hashtable. Below you can see we have created the $GroupBody hashtable.
$GroupBody = @{
DisplayName = "MyDynM365Group"
MailEnabled = $false
MailNickname = "MyDynM365Group"
SecurityEnabled = $true
GroupTypes = @(
'DynamicMembership','Unified'
)
MembershipRule = '(user.userPrincipalName -contains "ourcloudnetwork.com")'
membershipRuleProcessingState = 'On'
}Once the group settings have been defined, we can simply run New-MgGroup and define the variable, as follows:
New-MgGroup -BodyParameter $GroupBodyHow to add group owners and group members
Adding group owners and group members is not natively supported by New-MgGroup cmdlet, even though the -member and -owner parameters are available in v1 of the Microsoft Graph PowerShell module, this is because they were generated automatically from the Graph API. Version 2 of the Microsoft Graph PowerShell module removes these parameters.
If you want to add group owners or group members to your group in a single command, you must define them in a hashtable with the odata.bind mechanism. Again using the above command as an example, here is would it look like to add owners and members to our group within the hashtable during the group creation.
$GroupBody = @{
DisplayName = "MyDynM365Group"
MailEnabled = $false
MailNickname = "MyDynM365Group"
SecurityEnabled = $true
GroupTypes = @(
'DynamicMembership','Unified'
)
MembershipRule = '(user.userPrincipalName -contains "ourcloudnetwork.com")'
membershipRuleProcessingState = 'On'
"[email protected]" = @(
"https://graph.microsoft.com/v1.0/users/[email protected]",
)
"[email protected]" = @(
"https://graph.microsoft.com/v1.0/users/[email protected]",
)
}
New-MgGroup -BodyParameter $GroupBodyIf you do not want to use the above method, you will need to use the New-MgGroupMemberByRef or New-MgGroupOwnerByRef cmdlets.
- Command: New-MgGroupMemberByRef
- Module: Microsoft.Graph.Groups
- Permissions (least permissive): GroupMember.ReadWrite.All
- Command: New-MgGroupOwnerByRef
- Module: Microsoft.Graph.Groups
- Permissions (least permissive): Group.ReadWrite.All
You can use the below example to add a single user to a group as a member. You can also add an additional line within the $params hashtable to add multiple users at once.
$upn = "[email protected]"
$Groupid = (Get-MgGroup | Where-Object {$_.DisplayName -eq "MyDynM365Group2"}).id
$params = @{
"@odata.id" = "https://graph.microsoft.com/v1.0/users/$upn"
}
New-MgGroupMemberByRef -GroupId $GroupId -BodyParameter $params
Be mindful, however! If you try to add a member to a group using this method with a dynamic membership you will get the following error:
New-MgGroupMemberByRef_Create: Insufficient privileges to complete the operation.
Which is less than helpful as the error gives you a false reason for failure and could lead you down a rabbit hole of trying to fix a permissions issue that does not exist!
To add an owner to your group the same process can be followed, however, you just need to change the final line of the script. It does not matter if your group membership is dynamic for this command, if you get an error, the error is likely true.
New-MgGroupOwnerByRef -GroupId $GroupId -BodyParameter $params
Hello Daniel, I have ran the bellow command with no success.
New-MgGroup -DisplayName ‘MyDynM365Group’ `
-MailEnabled:$False `
-MailNickName ‘MyDynM365Group’ `
-SecurityEnabled `
-GroupTypes DynamicMembership,Unified `
-MembershipRule ‘(user.userPrincipalName -contains “ourcloudnetwork.com”)’ `
-MembershipRuleProcessingState On
Here is the error message I got.
New-MgGroup : Tenant does not have proper license.
Status: 400 (BadRequest)
ErrorCode: NoLicenseForOperation
Date: 2023-12-26T16:04:48
I could not find a solution. Can you help me with that?
Hi Martin,
Microsoft Entra ID P1 licensing is required for dynamic group memberships.
Hope that helps!
Dan
One more question – why “-SecurityEnabled” is required even If I`m creating Unified group?
I’m not sure why it is required, but it is always returned through Graph, so I expect it will always be needed.
Hi, I`m using MS 365 E-5 for testing proposes. You mean that I need another type of license?
No that is the same license that I am using. Can you try using New-MgBetaGroup instead?
I got following error: “New-MgBetaGroup: The term ‘New-MgBetaGroup’ is not recognized as a name of a cmdlet, function, script file, or executable program.”
In which case you’ll need to install the Microsoft Graph PowerShell beta modules. Try Install-Module Microsoft.Graph.Beta -scope currentuser.
Personally, I run the beta modules in PowerShell 7 only and the regular modules in PowerShell 5.