New-MgGroup: How to Create Microsoft 365 Groups with Graph PowerShell

The New-MgGroup cmdlet in Microsoft Graph PowerShell is a powerful tool for creating Microsoft 365 Groups. This article will guide you through the prerequisites, syntax, usage examples, cmdlet tips and possible errors and solutions.

Prerequisites

• Install the Microsoft Graph PowerShell module by running Install-Module Microsoft.Graph -Scope CurrentUser.
• Connect to Microsoft Graph with the necessary permissions:

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

Cmdlet Syntax

The basic syntax of the New-MgGroup cmdlet is as follows:

New-MgGroup -DisplayName <String> -MailNickname <String> -GroupTypes <String[]> -MailEnabled <Boolean> -SecurityEnabled <Boolean>

Usage Examples

Example 1: Create a Security Group

New-MgGroup -DisplayName "Security Group 1" -MailNickname "SecGroup1" -SecurityEnabled -MailEnabled:$false

Example 2: Create an Office 365 Group (Unified Group)

New-MgGroup -DisplayName "Office 365 Group 1" -MailNickname "O365Group1" -GroupTypes "Unified" -MailEnabled:$true

Example 3: Creating Multiple Office 365 Groups by Reading Data from a CSV File

You can create multiple Office 365 groups at once by reading group details from a CSV file. Here’s how you can do it:

CSV File Example:

DisplayName,MailNickname,Description
HR Team 1000,HRTeam1000,Group for HR 1000 department
Sales Team 1000,SalesTeam1000,Group for Sales 1000 department
IT Team 1000,ITTeam1000,Group for IT 1000 department

PowerShell Script:

$groups = Import-Csv -Path "C:\Path\To\Groups.csv"

foreach ($group in $groups) {
    $groupParams = @{
    DisplayName     = $group.DisplayName
    MailNickname    = $group.MailNickname
    Description     = $group.Description
    GroupTypes      = @("Unified")
    MailEnabled     = $true
    SecurityEnabled = $false
}
New-MgGroup -BodyParameter $groupParams
}

Example 4: Creating Dynamic Office 365 Groups

Setting the GroupTypes to DynamicMembership value and adding MembershipRule and MembershipRuleProcessingState creates Office 365 Groups that are dynamic in nature.

$groupParams = @{
    DisplayName   = "Regional Dept Dynamic Group"
    MailNickname  = "dynamicgroup"
    GroupTypes    = @("Unified", "DynamicMembership")
    MailEnabled   = $true
    SecurityEnabled = $false
    MembershipRule  = '(user.department -eq "Regional")'
    MembershipRuleProcessingState = "On"
}
New-MgGroup -BodyParameter $groupParams
                    

Example 5: Create a Private Microsoft 365 Group

Connect-MgGraph -Scopes "Group.ReadWrite.All"
$GroupParams = @{
    DisplayName     = "Finance Leadership Team"
    MailNickname    = "financeleadership"
    Description     = "Private Microsoft 365 group for finance leadership collaboration"
    GroupTypes      = @("Unified")
    MailEnabled     = $true
    SecurityEnabled = $false
    Visibility      = "Private"
}
New-MgGroup -BodyParameter $GroupParams

                    

What this script does

This script creates a private Microsoft 365 group using New-MgGroup. The key property here is Visibility = "Private", which ensures that group content is visible only to approved members.

Why this example is useful

This is useful for creating groups for leadership teams, HR, finance, legal, internal projects, or any team where group membership and shared content should be restricted.

Use Cases

1. Creating Groups for Departmental Collaboration:
• Scenario: Each department within an organization requires its own dedicated Office 365 group to manage communications, file sharing, and collaboration.
• Implementation: Use New-MgGroup to create groups for each department, ensuring they have the necessary resources like a shared mailbox, SharePoint site, and Planner.
• Benefit: Streamlines the process of setting up structured collaboration environments for departments, improving communication and resource management.


2. Setting Up Project-Based Groups:
• Scenario: For each new project, a dedicated Office 365 group is needed to facilitate collaboration among team members.
• Implementation: Use New-MgGroup to create project-specific groups that can include internal members and external partners, with controlled access to files and communications.
• Benefit: Enhances project management by providing a centralized space for all project-related activities, ensuring that only authorized users have access.


3. Automating Group Creation for New Teams::
• Scenario: When new teams or departments are formed, creating their Office 365 groups manually can be time-consuming.
• Implementation: Automate the creation of these groups using New-MgGroup, driven by a script that reads team details from a CSV file or database.
• Benefit: Saves time and ensures that new teams have immediate access to necessary collaboration tools without manual intervention.

Cmdlet Tips

• MailNickname: The MailNickname must be unique within your organization. Ensure you check for duplicates before running the cmdlet.
• GroupTypes: For creating Office 365 Groups set -GroupTypes to "Unified". For security groups, you can omit this parameter or set it to @().
• SecurityEnabled: Set to $true for security groups and $false for Office 365 Groups.
• MailEnabled: Set to $true for Office 365 Groups and $false for security groups.

Possible Errors and Solutions

if (Get-MgGroup -Filter "DisplayName eq 'GroupName'" -All) {
    Write-Error "A group with the name 'GroupName' already exists."
    } else {
    New-MgGroup -DisplayName "GroupName" -MailNickname "GroupName"
    }

Frequently Asked Questions

• What is New-MgGroup used for?
  New-MgGroup is a Microsoft Graph PowerShell cmdlet used to create Microsoft 365 groups. It allows specifying properties like display name, mail nickname, group type, and membership settings.
• How can I create a new Microsoft 365 group?
  Use the following script to create a group:

  $Body = @{
  displayName = "New Group Name"
  mailNickname = "NewGroup"
  groupTypes = @("Unified")
  mailEnabled = $true
  securityEnabled = $false
  }
  New-MgGroup -BodyParameter $Body

• Can I create multiple groups using a CSV file?
  Yes, prepare a CSV file with the following format:
  

  DisplayName,MailNickname,MailEnabled,SecurityEnabled
  Group 1,Group1,$true,$false
  Group 2,Group2,$true,$false

  
  Use this script to process the CSV and create groups:
  

  $Groups = Import-Csv -Path "C:\Path\To\File.csv"
  foreach ($Group in $Groups) {
  $Body = @{
      displayName = $Group.DisplayName
      mailNickname = $Group.MailNickname
      mailEnabled = [bool]::Parse($Group.MailEnabled)
      securityEnabled = [bool]::Parse($Group.SecurityEnabled)
      groupTypes = @("Unified")
  }
  New-MgGroup -BodyParameter $Body
  }

• What permissions are required to create Microsoft 365 groups?
  You need the Group.ReadWrite.All permission in Microsoft Graph PowerShell. Ensure the appropriate delegated or application permissions are granted.
• How can I add owners to a Microsoft 365 group during its creation?
  While the New-MgGroup cmdlet does not directly support adding owners during group creation, you can assign owners afterward using the New-MgGroupOwner cmdlet. Here's how
  

  $groupParams = @{
  DisplayName     = "Project Team"
  MailNickname    = "projectteam"
  GroupTypes      = @("Unified")
  MailEnabled     = $true
  SecurityEnabled = $false
  }
  $group = New-MgGroup -BodyParameter $groupParams
  
  # Add an owner to the group
  New-MgGroupOwner -GroupId $group.Id -DirectoryObjectId "<OwnerObjectId>"
  

• Can I create a dynamic membership group using New-MgGroup?
  Yes, you can create a dynamic membership group by specifying a membership rule during the group's creation. Here's an example:
  

  $groupParams = @{
  DisplayName  = "Dynamic Group"
  MailNickname = "dynamicgroup"
  GroupTypes  = @("Unified", "DynamicMembership")
  MailEnabled  = $true
  SecurityEnabled  = $false
  MembershipRule  = '(user.department -eq "Sales")'
  MembershipRuleProcessingState  = "On"
  }
  New-MgGroup -BodyParameter $groupParams

• What are the differences between security groups and Microsoft 365 groups created with New-MgGroup?
  When creating groups with New-MgGroup, setting the GroupTypes parameter to @("Unified") creates a Microsoft 365 group, which includes collaboration features like shared mailboxes and SharePoint sites. Omitting the GroupTypes parameter or setting it to an empty array creates a security group, primarily used for assigning permissions to resources.

By understanding these aspects of the New-MgGroup cmdlet, administrators can effectively create and manage groups within their Microsoft 365 environments, tailoring them to meet organizational needs.

• Can I create a private Microsoft 365 group using New-MgGroup?

Yes. Set the Visibility property to "Private" while creating the Microsoft 365 group.

$GroupParams = @{
    DisplayName     = "Private Project Group"
    MailNickname    = "privateprojectgroup"
    GroupTypes      = @("Unified")
    MailEnabled     = $true
    SecurityEnabled = $false
    Visibility      = "Private"
}

New-MgGroup -BodyParameter $GroupParams

                        

• Can I create a group without enabling email?

Yes. You can create a non-mail-enabled security group by setting MailEnabled to $false and SecurityEnabled to $true.

New-MgGroup `
    -DisplayName "App Access Group" `
    -MailNickname "appaccessgroup" `
    -MailEnabled:$false `
    -SecurityEnabled:$true

This type of group is typically used for access control, app assignments, and permission management rather than collaboration.

Adding Group Using Microsoft 365 Admin Center

1. Login into Microsoft 365 Admin Center
2. Select Groups >> Active Teams & Groups page. Click Add a Microsoft 365 group button.

3. Enter basic group details like Group Name and Group Description

4. Click "Assign Owners" >> Select the Group Owner >> Click "Add" button.

5. Click "Add Members" >> Select the Group Members >> Click "Add" button.

6. Specify group email address and group visibility (public or private) and click Next button.

7. Review the group details and click Create Group button.

Conclusion

The New-MgGroup cmdlet is a versatile and essential tool for managing Microsoft 365 Groups. By understanding its prerequisites, syntax, and usage you can efficiently create and manage groups within your organization. Remember to handle common errors and use cmdlet tips to streamline your group management tasks.

If You Prefer the Graph API Way

Note: To create Microsoft 365 or Security groups using Graph API, you must POST to /groups with the appropriate property set (Unified or Security). For bulk operations, use a CSV to define multiple groups and loop through them in PowerShell.

Create a Microsoft 365 (Unified) Group

$groupPayload = @{
displayName     = "Marketing Team"
description     = "Group for marketing collaboration"
groupTypes      = @("Unified")
mailEnabled     = $true
mailNickname    = "marketingteam"
securityEnabled = $false
visibility      = "Private"
}

Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/groups" -Body ($groupPayload | ConvertTo-Json -Depth 10)

Create a Microsoft 365 Security Group

$groupPayload = @{
displayName     = "Helpdesk Staff"
description     = "Access control group for helpdesk tools"
mailEnabled     = $false
mailNickname    = "helpdeskstaff"
securityEnabled = $true
}

Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/groups" -Body ($groupPayload | ConvertTo-Json -Depth 10)

Create Groups in Bulk from CSV

# Sample CSV headers: displayName,mailNickname,description,groupType,visibility
$csvPath = "C:\Users\admin\Documents\new-groups.csv"
$groups = Import-Csv -Path $csvPath

foreach ($group in $groups) {
$groupPayload = @{
displayName     = $group.displayName
description     = $group.description
mailNickname    = $group.mailNickname
mailEnabled     = if ($group.groupType -eq "Unified") { $true } else { $false }
securityEnabled = if ($group.groupType -eq "Unified") { $false } else { $true }
groupTypes      = if ($group.groupType -eq "Unified") { @("Unified") } else { @() }
}

if ($group.visibility) {
$groupPayload["visibility"] = $group.visibility
}

Invoke-MgGraphRequest -Method POST -Uri "https://graph.microsoft.com/v1.0/groups" -Body ($groupPayload | ConvertTo-Json -Depth 10)
}

CSV Format Example

displayName,mailNickname,description,groupType,visibility
Marketing Team,marketingteam,Group for marketing collaboration,Unified,Private
Helpdesk Staff,helpdeskstaff,Access control group for helpdesk tools,Security,

• 💡 For Security groups, you can leave the visibility field blank.

Required Permissions

You must have one of the following:

• Group.ReadWrite.All
• Directory.ReadWrite.All

Graph API Documentation

👉 POST /groups - Microsoft Graph v1.0

Related Articles: