Gestion des groupes dans Microsoft Graph

Article
10/14/2024

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 le type de ressource de groupe et ses API associées pour créer et gérer différents types de groupes et de fonctionnalités de groupe.

Remarque

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.
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.

Dans Microsoft Graph, le type de groupe peut être identifié par les paramètres de ses propriétés groupTypes, mailEnabled et securityEnabled . Le tableau suivant indique comment différencier les groupes par leurs paramètres et si les types de groupes peuvent être gérés via les API de groupes Microsoft Graph.

Type	groupTypes	mailEnabled	securityEnabled	Créé et géré via les API de 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; en lecture seule via Microsoft Graph
Groupes de distribution	`[]`	`true`	`false`	Non; en lecture seule via Microsoft Graph

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.

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 plus d'informations, voir Gérer les groupes de sécurité à extension de messagerie.

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, tous 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é groupTypes 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.

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

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



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



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

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


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


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


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


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

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.

Paramètres supplémentaires pour la sécurité et les groupes Microsoft 365

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

Setting	S’applique à
Expiration du groupe	Groupes Microsoft 365
Paramètres de groupe tels que si le groupe peut avoir des invités en tant que membres, des mots autorisés dans les noms de groupe, qui est autorisé à créer des groupes, et ainsi de suite	Groupes Microsoft 365
Paramètres pour synchroniser les groupes locaux avec le cloud, par exemple si l’écriture différée est activée	Sécurité et groupes Microsoft 365

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, et les licences sont ensuite héritées par les membres du groupe et automatiquement par les nouveaux membres. Lorsque les membres quittent le groupe, ces licences sont supprimées. La fonctionnalité ne peut être utilisée qu’avec les groupes de sécurité et les groupes Microsoft 365 dont securityEnabled est défini sur 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	Opérations d’API
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.	Créer un groupe Répertorier les groupes Mettre à jour un groupe Supprimer un groupe Renouveler les groupes sur le point d’expirer Restaurer des groupes Microsoft 365 supprimés
Gérer l’appartenance et la propriété d’un groupe
Répertoriez les membres d’un groupe, et ajoutez ou supprimez des membres.	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.	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.	Liste des propriétaires Ajouter un propriétaire Supprimer un propriétaire
Fonctionnalités de groupe pour les applications Microsoft 365
Gérer les conversations de groupe	Créer, obtenir ou supprimer
Planifier et gérer des événements de calendrier sur un calendrier de groupe	Créer, lister, obtenir, mettre à jour, supprimer
Gérer des blocs-notes OneNote pour un groupe	Créer, lister
Activer un groupe Microsoft pour Microsoft Teams	Create

Microsoft Entra rôles pour la gestion des groupes

Pour gérer des groupes dans des scénarios délégués, l’application doit disposer des autorisations Microsoft Graph appropriées et l’utilisateur connecté doit disposer d’un rôle Microsoft Entra pris en charge.

Les rôles Microsoft Entra suivants sont les rôles les moins privilégiés pour toutes les opérations de lecture et d’écriture sur les groupes via Microsoft Graph, à l’exception des groupes assignables à un rôle. Le rôle le moins privilégié pour la gestion des groupes assignables à un rôle est Administrateur de rôle privilégié.

Rédacteurs d'annuaires
administrateur Groupes
Administrateur d’utilisateurs

Pour obtenir un résumé des rôles d’administrateur les moins privilégiés pour différentes tâches liées aux groupes, consultez Rôles avec privilèges minimum pour gérer les groupes.

Vous pouvez également créer des rôles personnalisés pour les tâches liées aux groupes. Reportez-vous à la référence des rôles intégrés Microsoft Entra pour identifier les autorisations qui commencent par microsoft.directory/groups/ déduire les tâches spécifiques à l’autorisation et créer un rôle personnalisé avec les autorisations sélectionnées.

Étape suivante

Commencer à travailler avec des groupes

Partager via

Gestion des groupes dans Microsoft Graph

Regrouper les types dans Microsoft Entra ID et Microsoft Graph

Groupes Microsoft 365

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

Appartenance aux groupes

Appartenance dynamique

Autres types de groupes

Paramètres supplémentaires pour la sécurité et les groupes Microsoft 365

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

Gestion des licences en fonction des groupes

Cas d’utilisation courants

Microsoft Entra rôles pour la gestion des groupes

Étape suivante

Commentaires

Ressources supplémentaires