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 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/beta/$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"
}
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 lorsque vous appelez l’API des 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
oudevice.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 and
opérateurs , or
et 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/beta/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"
}
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/beta/$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/beta/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/beta/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 ?.
Propriétés stockées en dehors du magasin de données main
Bien que les données de ressources de groupe soient principalement stockées dans Microsoft Entra ID, certaines de ses propriétés, telles que autoSubscribeNewMembers et allowExternalSenders, sont stockées dans Microsoft Exchange. Dans la plupart des cas, vous ne pouvez pas spécifier ces propriétés dans le même corps de demande De création ou de mise à jour que les autres propriétés de groupe.
Les propriétés stockées en dehors du magasin de données main ne sont pas non plus prises en charge dans le cadre du suivi des modifications. Par conséquent, une modification de l’une de ces propriétés n’entraîne pas l’affichage d’un objet dans la réponse à la requête delta.
Cas d’utilisation courante pour l’API de groupes dans Microsoft Graph
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.