Working with groups in Microsoft Graph

Article
12/27/2024

Groups are collections of principals with shared access to resources in Microsoft services or in your app. Different principals such as users, other groups, devices, and applications can be part of groups. Using groups helps you avoid working with individual principals and simplifies management of access to your resources.

Microsoft Graph exposes the group resource type and its associated APIs to create and manage different types of groups and group functionality.

Note

Groups can only be created through work or school accounts. Personal Microsoft accounts don't support groups.
All group-related operations in Microsoft Graph require administrator consent.

Group types in Microsoft Entra ID and Microsoft Graph

Microsoft Entra ID supports the following types of groups.

Microsoft 365 groups
Security groups
Mail-enabled security groups
Distribution groups

Note

Microsoft also supports dynamic distribution groups which can't be managed or retrieved through Microsoft Graph.

In Microsoft Graph, the type of group can be identified by the settings of its groupTypes, mailEnabled, and securityEnabled properties. The following table indicates how to differentiate the groups by their settings, and whether the group types can be managed through the Microsoft Graph groups APIs.

Type	groupTypes	mailEnabled	securityEnabled	Created and managed via the groups APIs
Microsoft 365 groups	`["Unified"]`	`true`	`true` or `false`	Yes
Security groups	`[]`	`false`	`true`	Yes
Mail-enabled security groups	`[]`	`true`	`true`	No; read-only through Microsoft Graph
Distribution groups	`[]`	`true`	`false`	No; read-only through Microsoft Graph

For more information about groups in Microsoft Entra ID, see compare groups in Microsoft Entra ID.

Microsoft 365 groups

The power of Microsoft 365 groups is in its collaborative nature, perfect for people who work together on a project or a team. They're created with resources that members of the group share, including:

Outlook conversations
Outlook calendar
SharePoint files
OneNote notebook
SharePoint team site
Planner plans
Intune device management

The following JSON object shows a sample representation of a group when you call the Microsoft Graph groups API.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "4c5ee71b-e6a5-4343-9e2c-4244bc7e0938",
    "deletedDateTime": null,
    "classification": "MBI",
    "createdDateTime": "2016-08-23T14:46:56Z",
    "description": "This is a group in Outlook",
    "displayName": "OutlookGroup101",
    "groupTypes": [
        "Unified"
    ],
    "mail": "outlookgroup101@service.microsoft.com",
    "mailEnabled": true,
    "mailNickname": "outlookgroup101",
    "preferredLanguage": null,
    "proxyAddresses": [
        "smtp:outlookgroup101@contoso.com",
        "SMTP:outlookgroup101@service.microsoft.com"
    ],
    "securityEnabled": false,
    "theme": null,
    "visibility": "Public"
}

To learn more about Microsoft 365 groups, see Overview of Microsoft 365 groups in Microsoft Graph.

Security groups and mail-enabled security groups

Security groups are for controlling user access to resources. By checking whether a user is a member of a security group, your app can make authorization decisions when that user is trying to access some secure resources in your app. Security groups can have users, other security groups, devices, and service principals as members.

Mail-enabled security groups are used in the same way as security groups, but can be used to send emails to group members. Mail-enabled security groups can't be created or updated through the API; instead, they're read-only. For more information, see Manage mail-enabled security groups.

The following JSON object shows a sample representation of a security group when you call the Microsoft Graph groups API.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.group",
    "id": "f87faa71-57a8-4c14-91f0-517f54645106",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2016-07-20T09:21:23Z",
    "description": "This group is a Security Group",
    "displayName": "SecurityGroup101",
    "groupTypes": [],
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "",
    "preferredLanguage": null,
    "proxyAddresses": [],
    "securityEnabled": true
}

Group membership

Membership to groups can be statically assigned or dynamic. Not all object types can be members of both Microsoft 365 and security groups.

The following table shows the types of members that can be added to either security groups or Microsoft 365 groups.

Object type	Member of security group	Member of Microsoft 365 group
User
Security group
Microsoft 365 group
Device
Service principal
Organizational contact

Dynamic membership

Microsoft 365 and security groups can have dynamic membership rules that automatically add or remove members from the group based on the principal's properties. For example, a "Marketing employees" group can define a dynamic membership rule that only users with their department property set to "Marketing" can be members of the group. In this case, any users who leave the department are automatically removed from the group.

Only users and devices are supported as members in dynamic membership groups. You can create a dynamic membership group for devices or users, but not both.

The dynamic membership rules are specified through the membershipRule property during group creation. A single expression follows this syntax: Property Operator Value.

The Property is defined following this syntax: object.property. For example, user.department or device.accountEnabled.
The rule syntax supports various operators. For more information, see Supported expression operators.
A Value of type String must be enclosed in double quotes ("). You must use a backslash to escape any double quotes inside double quotes. This requirement doesn't apply when using the rule builder in the Microsoft Entra admin center because the expression isn't enclosed in double quotes.

The following example shows a complete rule.

"membershipRule": "user.department -eq \"Marketing\"".

You can combine multiple expressions in a rule using the and, or, and not operators.

The groupTypes property must also include the "DynamicMembership" value in the collection. The dynamic membership rule can be turned on or off through the membershipRuleProcessingState property. You can update a group with assigned membership to have dynamic membership.

The following example request creates a new Microsoft 365 group that can only include employees in the Marketing department.

POST https://graph.microsoft.com/v1.0/groups
Content-type: application/json

{
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mailEnabled": true,
    "mailNickname": "marketing",
    "securityEnabled": false,
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "on"
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new Group
{
	Description = "Marketing department folks",
	DisplayName = "Marketing department",
	GroupTypes = new List<string>
	{
		"Unified",
		"DynamicMembership",
	},
	MailEnabled = true,
	MailNickname = "marketing",
	SecurityEnabled = false,
	MembershipRule = "user.department -eq \"Marketing\"",
	MembershipRuleProcessingState = "on",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.PostAsync(requestBody);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



mgc groups create --body '{\
    "description": "Marketing department folks",\
    "displayName": "Marketing department",\
    "groupTypes": [\
        "Unified",\
        "DynamicMembership"\
    ],\
    "mailEnabled": true,\
    "mailNickname": "marketing",\
    "securityEnabled": false,\
    "membershipRule": "user.department -eq \"Marketing\"",\
    "membershipRuleProcessingState": "on"\
}\
'

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewGroup()
description := "Marketing department folks"
requestBody.SetDescription(&description) 
displayName := "Marketing department"
requestBody.SetDisplayName(&displayName) 
groupTypes := []string {
	"Unified",
	"DynamicMembership",
}
requestBody.SetGroupTypes(groupTypes)
mailEnabled := true
requestBody.SetMailEnabled(&mailEnabled) 
mailNickname := "marketing"
requestBody.SetMailNickname(&mailNickname) 
securityEnabled := false
requestBody.SetSecurityEnabled(&securityEnabled) 
membershipRule := "user.department -eq \"Marketing\""
requestBody.SetMembershipRule(&membershipRule) 
membershipRuleProcessingState := "on"
requestBody.SetMembershipRuleProcessingState(&membershipRuleProcessingState) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().Post(context.Background(), requestBody, nil)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Group group = new Group();
group.setDescription("Marketing department folks");
group.setDisplayName("Marketing department");
LinkedList<String> groupTypes = new LinkedList<String>();
groupTypes.add("Unified");
groupTypes.add("DynamicMembership");
group.setGroupTypes(groupTypes);
group.setMailEnabled(true);
group.setMailNickname("marketing");
group.setSecurityEnabled(false);
group.setMembershipRule("user.department -eq \"Marketing\"");
group.setMembershipRuleProcessingState("on");
Group result = graphClient.groups().post(group);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


const options = {
	authProvider,
};

const client = Client.init(options);

const group = {
    description: 'Marketing department folks',
    displayName: 'Marketing department',
    groupTypes: [
        'Unified',
        'DynamicMembership'
    ],
    mailEnabled: true,
    mailNickname: 'marketing',
    securityEnabled: false,
    membershipRule: 'user.department -eq \"Marketing\"',
    membershipRuleProcessingState: 'on'
};

await client.api('/groups')
	.post(group);

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\Group;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new Group();
$requestBody->setDescription('Marketing department folks');
$requestBody->setDisplayName('Marketing department');
$requestBody->setGroupTypes(['Unified', 'DynamicMembership', 	]);
$requestBody->setMailEnabled(true);
$requestBody->setMailNickname('marketing');
$requestBody->setSecurityEnabled(false);
$requestBody->setMembershipRule('user.department -eq \"Marketing\"');
$requestBody->setMembershipRuleProcessingState('on');

$result = $graphServiceClient->groups()->post($requestBody)->wait();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


Import-Module Microsoft.Graph.Groups

$params = @{
	description = "Marketing department folks"
	displayName = "Marketing department"
	groupTypes = @(
	"Unified"
"DynamicMembership"
)
mailEnabled = $true
mailNickname = "marketing"
securityEnabled = $false
membershipRule = "user.department -eq "Marketing""
membershipRuleProcessingState = "on"
}

New-MgGroup -BodyParameter $params

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Group(
	description = "Marketing department folks",
	display_name = "Marketing department",
	group_types = [
		"Unified",
		"DynamicMembership",
	],
	mail_enabled = True,
	mail_nickname = "marketing",
	security_enabled = False,
	membership_rule = "user.department -eq \"Marketing\"",
	membership_rule_processing_state = "on",
)

result = await graph_client.groups.post(request_body)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

The request returns a 201 Created response code and the newly created group object in the response body.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "6f7cd676-5445-47c4-9c2b-c47da4671da2",
    "createdDateTime": "2023-01-20T07:00:31Z",
    "description": "Marketing department folks",
    "displayName": "Marketing department",
    "groupTypes": [
        "Unified",
        "DynamicMembership"
    ],
    "mail": "marketing@contoso.com",
    "mailEnabled": true,
    "mailNickname": "marketing",
    "membershipRule": "user.department -eq \"Marketing\"",
    "membershipRuleProcessingState": "On"
}

To learn more about formulating membership rules, see Dynamic membership rules for groups in Microsoft Entra ID.

Note

Dynamic membership rules requires the tenant to have at least a Microsoft Entra ID P1 license for each unique user that is a member of one or more dynamic groups.

Other types of groups

Microsoft 365 groups in Yammer are used to facilitate user collaboration through Yammer posts. This type of group can be returned through a read request, but their posts can't be accessed through the API. When Yammer posts and conversation feeds are enabled on a group, default Microsoft 365 group conversations are disabled. To learn more, see Yammer developer API docs.

Additional settings for security and Microsoft 365 groups

Apart from configuring the properties on the group resource, you can also configure the following settings for groups.

Setting	Applies to
Group expiration	Microsoft 365 groups
Group settings such as whether the group can have guests as members, allowed words in group names, who is allowed to create groups, and so on	Microsoft 365 groups
Settings to synchronize on-premises groups with the cloud, such as whether writeback is enabled	Security and Microsoft 365 groups

Group search limitations for guest users in organizations

Group search capabilities allow the app to search for any groups in an organization's directory by performing queries against the /groups resource (for example, https://graph.microsoft.com/v1.0/groups). Both administrators and users who are members have this capability; however, guest users don't.

If the signed-in user is a guest user, depending on the permissions an app has been granted, it can read the profile of a specific group (for example, https://graph.microsoft.com/v1.0/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc); however, it can't perform queries against the /groups resource that potentially returns more than a single resource.

With the appropriate permissions, the app can read the profiles of groups that it obtains by following links in navigation properties; for example, /groups/{id}/members.

For more information about what guest users can do with groups, see Compare member and guest default permissions.

Group-based licensing

You can use group-based licensing to assign one or more product licenses to a Microsoft Entra group, and the licenses are then inherited by the members of the group, and automatically by any new members. When members leave the group, those licenses are removed. The feature can only be used with security groups and Microsoft 365 groups that have securityEnabled set to true.

To learn more about group-based licensing, see What is group-based licensing in Microsoft Entra ID?.

Properties stored outside the main data store

While the group resource data is mostly stored in Microsoft Entra ID, some of its properties, like autoSubscribeNewMembers and allowExternalSenders, are stored in Microsoft Exchange. In most instances, you can't specify these properties in the same Create or Update request body as other group properties.

Properties stored outside the main data store also aren't supported as part of change tracking. Therefore, a change to any of these properties doesn't result in an object showing up in the delta query response.

The following properties on the group object are stored outside the main data store: accessType, allowExternalSenders, autoSubscribeNewMembers, cloudLicensing, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount, membershipRuleProcessingStatus, isArchived.

Common use cases

Using Microsoft Graph, you can perform the following common operations on groups.

Use cases	API operations
Create groups, manage group characteristics
Create new groups, get existing groups, update the properties on groups, and delete groups.	Create new groups List groups Update groups Delete groups Renew groups that are about to expire Restore deleted Microsoft 365 groups
Manage group membership and ownership
List the members of a group, and add or remove members.	List members Add member Remove member
Determine whether a user is a member of a group, get all the groups the user is a member of.	Check member groups Get member groups
List the owners of a group, and add or remove owners.	List owners Add owner Remove owner
Group functionality for Microsoft 365 apps
Manage group conversations	Create, get, or delete
Schedule and manage calendar events on a group calendar	Create, list, get, update, delete
Manage OneNote notebooks for a group	Create, list
Enable a Microsoft group for Microsoft Teams	Create

Microsoft Entra roles for managing groups

To manage groups in delegated scenarios, the app must be granted the appropriate Microsoft Graph permissions and the signed-in user must be in a supported Microsoft Entra role.

The following Microsoft Entra roles are the least privileged roles for all read and write operations on groups through Microsoft Graph, except for role-assignable groups. The least privileged role for managing role-assignable groups is Privileged Role Administrator.

Directory Writers
Groups Administrator
User Administrator

For a summary of the least privileged admin roles for different group-related tasks, see Least privileged roles to manage groups.

You can also create custom roles for group-related tasks. Refer to the Microsoft Entra built-in roles reference to identify permissions that start with microsoft.directory/groups/ which infer the permission-specific tasks, and create a custom role with the selected permissions.

Next step

Start working with groups

Share via

Working with groups in Microsoft Graph

Group types in Microsoft Entra ID and Microsoft Graph

Microsoft 365 groups

Security groups and mail-enabled security groups

Group membership

Dynamic membership

Other types of groups

Additional settings for security and Microsoft 365 groups

Group search limitations for guest users in organizations

Group-based licensing

Properties stored outside the main data store

Common use cases

Microsoft Entra roles for managing groups

Next step

Feedback

Additional resources