Gestion des groupes dans Microsoft Graph

Les groupes sont des collections de principaux qui partagent l’accès à des ressources dans les services Microsoft ou dans votre application. Différents principaux tels que des utilisateurs, d’autres groupes, des appareils et des applications peuvent faire partie de groupes. L’utilisation de groupes vous permet d’éviter d’utiliser des principaux individuels et simplifie la gestion de l’accès à vos ressources.

Microsoft Graph expose l’API de groupes pour créer et gérer différents types de groupes et les fonctionnalités de groupe.

Remarque

1. Les groupes peuvent uniquement être créés par le biais de comptes professionnels ou scolaires. Les comptes Microsoft personnels ne prennent pas en charge les groupes.
2. Toutes les opérations liées aux groupes dans Microsoft Graph nécessitent l’accord de l’administrateur.

Regrouper les types dans Microsoft Entra ID et Microsoft Graph

Microsoft Entra ID prend en charge les types de groupes suivants.

• Groupes Microsoft 365
• Groupes de sécurité
• Groupes de sécurité à extension messagerie
• Groupes de distribution

Remarque

Microsoft prend également en charge les groupes de distribution dynamiques qui ne peuvent pas être gérés ou récupérés via Microsoft Graph.

Seuls Microsoft 365 et les groupes de sécurité peuvent être gérés via l’API des groupes Microsoft Graph. Les groupes de distribution et à extension courrier sont accessibles en lecture seule via Microsoft Graph.

Dans Microsoft Graph, le type de groupe peut être identifié par les paramètres de ses propriétés groupType, mailEnabled et securityEnabled , comme indiqué dans le tableau ci-dessous.

Type	groupType	mailEnabled	securityEnabled	Créé et géré via l’API des groupes
Groupes Microsoft 365	["Unified"]	true	true ou false	Oui
Groupes de sécurité	[]	false	true	Oui
Groupes de sécurité à extension messagerie	[]	true	true	Non
Groupes de distribution	[]	true	false	Non

Pour plus d’informations sur les groupes, voir les sections ci-dessous. Pour plus d’informations sur les groupes dans Microsoft Entra ID, consultez Comparer des groupes dans Microsoft Entra ID.

Groupes Microsoft 365

La puissance des groupes Microsoft 365 repose sur leur nature collaborative, idéale pour les personnes qui travaillent conjointement sur un projet ou pour les équipes. Ils sont créés avec les ressources partagées par les membres du groupe, y compris les ressources suivantes :

• conversations Outlook ;
• calendrier Outlook ;
• fichiers SharePoint ;
• bloc-notes OneNote ;
• site d’équipe SharePoint ;
• plans du planificateur ;
• gestion des périphériques dans Intune.

L’objet JSON suivant montre un exemple de représentation d’un groupe lorsque vous appelez l’API des groupes Microsoft Graph.

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"
}

Pour en savoir plus sur les groupes Microsoft 365, consultez Vue d’ensemble des groupes Microsoft 365 dans Microsoft Graph.

Paramètres des groupes Microsoft 365

Outre la configuration des propriétés de groupe standard, vous pouvez également configurer les paramètres suivants pour les groupes Microsoft 365.

• Expiration du groupe
• Paramètres de groupe , par exemple, si le groupe peut avoir des invités en tant que membres, qui est autorisé à créer des groupes, des mots autorisés dans les noms de groupes, etc.

Groupes de sécurité et groupes de sécurité à extension messagerie

Les Groupes de sécurité servent à contrôler l’accès des utilisateurs aux ressources. En vérifiant si un utilisateur est membre d’un groupe de sécurité, votre application peut prendre des décisions d’autorisation lorsque ledit utilisateur tente d’accéder à certaines ressources sécurisées dans l’application. Les groupes de sécurité peuvent avoir des utilisateurs, d’autres groupes de sécurité, des appareils et des principaux de services en tant que membres.

Les groupes de sécurité à extension messagerie sont utilisés de la même façon que les groupes de sécurité, mais peuvent être utilisés pour envoyer des e-mails aux membres du groupe. Les groupes de sécurité à extension messagerie ne peuvent pas être créés ou mis à jour via l’API ; au lieu de cela, ils sont en lecture seule. Pour en savoir plus, consultez la rubrique Gérer les groupes de sécurité à extension messagerie dans Exchange 2016.

L’objet JSON suivant montre un exemple de représentation d’un groupe de sécurité lorsque vous appelez l’API de groupes Microsoft Graph.

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
}

Appartenance aux groupes

L’appartenance à des groupes peut être affectée de manière statique ou dynamique. Tous les types d’objets ne peuvent pas être membres de Microsoft 365 et de groupes de sécurité.

Le tableau suivant présente les types de membres qui peuvent être ajoutés à des groupes de sécurité ou à des groupes Microsoft 365.

Type d’objet	Membre du groupe de sécurité	Membre du groupe Microsoft 365
Utilisateur
Groupe de sécurité
Groupe Microsoft 365
Appareil
Principal de service
Contact de l’organisation

Appartenance dynamique

Microsoft 365 et les groupes de sécurité peuvent avoir des règles d’appartenance dynamique qui ajoutent ou suppriment automatiquement des membres du groupe en fonction des propriétés du principal. Par exemple, un groupe « Employés marketing » peut définir une règle d’appartenance dynamique selon laquelle seuls les utilisateurs dont la propriété de service est définie sur « Marketing » peuvent être membres du groupe. Dans ce cas, les utilisateurs qui quittent le service sont automatiquement supprimés du groupe.

Seuls les utilisateurs et les appareils sont pris en charge en tant que membres dans les groupes d’appartenance dynamiques. Vous pouvez créer un groupe d’appartenance dynamique pour les appareils ou les utilisateurs, mais pas les deux.

Les règles d’appartenance dynamique sont spécifiées via la propriété membershipRule lors de la création du groupe. Une seule expression suit cette syntaxe : Property Operator Value.

• le Property est défini en suivant cette syntaxe : object.property. Par exemple user.department ou device.accountEnabled.
• La syntaxe de règle prend en charge différents opérateurs. Pour plus d’informations, consultez Opérateurs d’expression pris en charge.
• Un Value de type String doit être placé entre guillemets doubles (« ). Vous devez utiliser une barre oblique inverse pour échapper les guillemets doubles entre guillemets doubles. Cette exigence ne s’applique pas lors de l’utilisation du générateur de règles dans le centre d'administration Microsoft Entra, car l’expression n’est pas placée entre guillemets doubles.

L’exemple suivant montre une règle complète.

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

Vous pouvez combiner plusieurs expressions dans une règle à l’aide des andopérateurs , oret not .

La propriété groupType doit également inclure la "DynamicMembership" valeur dans la collection. La règle d’appartenance dynamique peut être activée ou désactivée via la propriété membershipRuleProcessingState. Vous pouvez mettre à jour un groupe avec l’appartenance affectée pour qu’il ait une appartenance dynamique.

L’exemple de requête suivant crée un groupe Microsoft 365 qui ne peut inclure que les employés du service Marketing.

HTTP

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"
}

C#

// 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);

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
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"\
}\
'

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


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) 

groups, err := graphClient.Groups().Post(context.Background(), requestBody, nil)

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Java

// 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);

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

JavaScript

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);

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PHP

<?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();

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

PowerShell

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

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

Python

from msgraph import GraphServiceClient
from msgraph.generated.models.group import Group

graph_client = GraphServiceClient(credentials, scopes)

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)

Pour plus d’informations sur la façon d'ajouter le Kit de développement logiciel (SDK) à votre projet et créer une instance authProvider, consultez la documentation du Kit de développement logiciel (SDK).

La requête retourne un 201 Created code de réponse et l’objet groupe nouvellement créé dans le corps de la réponse.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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"
}

Pour en savoir plus sur la formulation de règles d’appartenance, consultez Règles d’appartenance dynamique pour les groupes dans Microsoft Entra ID.

Remarque

Les règles d’appartenance dynamique nécessitent que le locataire dispose d’au moins une licence Microsoft Entra ID P1 pour chaque utilisateur unique membre d’un ou plusieurs groupes dynamiques.

Autres types de groupes

Les groupes Microsoft 365 dans Yammer sont utilisés pour faciliter la collaboration entre les utilisateurs via les billets Yammer. Ce type de groupe peut être renvoyé via une demande de lecture, mais l’API ne permet pas d’accéder aux billets. Lorsque les flux de conversation et les billets Yammer sont activés dans un groupe, les conversations de groupe Microsoft 365 par défaut sont désactivées. Pour plus d’informations, consultez les documents sur l’API Développeur Yammer.

Limitations de la recherche de groupes pour les utilisateurs invités dans les organisations

Les fonctionnalités de recherche de groupe permettent à l’application de rechercher des groupes dans le répertoire d’un organization en effectuant des requêtes sur la /groups ressource (par exemple, https://graph.microsoft.com/v1.0/groups). Les administrateurs et les utilisateurs qui sont membres disposent de cette fonctionnalité ; Toutefois, ce n’est pas le cas des utilisateurs invités.

Si l'utilisateur connecté est un utilisateur invité, selon les autorisations accordées à l'application, celle-ci peut lire le profil d'un groupe spécifique (par exemple, https://graph.microsoft.com/v1.0/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc) ; cependant, elle ne peut pas effectuer de requêtes sur la ressource qui renvoie potentiellement plus d'une seule ressource/groups.

Avec les autorisations appropriées, l'application peut lire les profils des groupes qu'elle obtient en suivant les liens dans les propriétés de navigation ; par exemple, /groups/{id}/members.

Pour plus d'informations sur ce que les utilisateurs invités peuvent faire avec les groupes, voir Comparer les autorisations par défaut des membres et des invités.

Gestion des licences en fonction des groupes

Vous pouvez utiliser des licences basées sur des groupes pour attribuer une ou plusieurs licences de produit à un groupe Microsoft Entra. Microsoft Entra ID garantit que les licences sont attribuées à tous les membres du groupe. Les nouveaux membres qui rejoignent le groupe bénéficient des licences appropriées. Lorsqu’ils quittent le groupe, ces licences sont supprimées. La fonctionnalité peut seulement être utilisée avec les groupes de sécurité et les groupes Microsoft 365 ayant securityEnabled=TRUE. Pour en savoir plus sur les licences basées sur les groupes, consultez Qu’est-ce que les licences basées sur les groupes dans Microsoft Entra ID ?.

Cas d’utilisation courants

L’utilisation de Microsoft Graph vous permet d’effectuer les opérations courantes suivantes sur des groupes.

Cas d’utilisation	Ressources REST	Voir aussi
Créer des groupes, gérer les caractéristiques de groupe
Créez des groupes, obtenez des groupes existants, mettez à jour les propriétés de groupes et supprimez des groupes. Actuellement, seuls les groupes de sécurité et les groupes dans Outlook peuvent être créés via l’API.	groupe	Créer un groupe Répertorier les groupes Mettre à jour un groupe Supprimer un groupe
Gestion de l’appartenance aux groupes
Répertoriez les membres d’un groupe, et ajoutez ou supprimez des membres.	utilisateur groupe	Répertorier les membres Ajouter un membre Supprimer un membre
Déterminez si un utilisateur est membre d’un groupe, obtenez tous les groupes dont l’utilisateur est membre.	utilisateur groupe servicePrincipal orgContact	Vérifier des groupes de membres Obtenir des groupes de membres
Répertoriez les propriétaires d’un groupe, et ajoutez ou supprimez des propriétaires.	utilisateur groupe	Répertorier les propriétaires Ajouter un membre Supprimer un membre