Trabajar con grupos en Microsoft Graph

Los grupos son colecciones de entidades de seguridad con acceso compartido a recursos en servicios Microsoft o en la aplicación. Diferentes entidades de seguridad, como usuarios, otros grupos, dispositivos y aplicaciones, pueden formar parte de grupos. El uso de grupos le ayuda a evitar trabajar con entidades de seguridad individuales y simplifica la administración del acceso a los recursos.

Microsoft Graph expone la API de grupos para crear y administrar diferentes tipos de grupos y funcionalidad de grupo.

Nota:

1. Los grupos sólo pueden crearse a través de las cuentas del trabajo o de la escuela.. Las cuentas personales de Microsoft no admiten grupos.
2. Todas las operaciones relacionadas con grupos de Microsoft Graph requieren permisos de administrador.

Tipos de grupo en Microsoft Entra ID y Microsoft Graph

Microsoft Entra ID admite los siguientes tipos de grupos.

• Grupos de Microsoft 365
• Grupos de seguridad
• Grupos de seguridad habilitados para correo
• Grupos de distribución

Nota:

Microsoft también admite grupos de distribución dinámicos que no se pueden administrar ni recuperar mediante Microsoft Graph.

Solo se pueden administrar grupos de seguridad y Microsoft 365 a través de la API de grupos de Microsoft Graph. Los grupos de distribución y habilitados para correo son de solo lectura a través de Microsoft Graph.

En Microsoft Graph, el tipo de grupo puede ser identificado por la configuración de sus propiedades groupType, mailEnabled, y securityEnabled como se indica en la siguiente tabla.

Tipo	groupType	mailEnabled	securityEnabled	Creado y administrado a través de la API de grupos
Grupos de Microsoft 365	["Unified"]	true	true o false	Sí
Grupos de seguridad	[]	false	true	Sí
Grupos de seguridad habilitados para correo	[]	true	true	No
Grupos de distribución	[]	true	false	No

Para más información acerca de los grupos, vea las secciones siguientes. Para obtener más información sobre los grupos de Microsoft Entra ID, vea Comparar grupos en Microsoft Entra ID.

Grupos de Microsoft 365

La utilidad de los grupos de Microsoft 365 reside en su naturaleza colaborativa, ideal para personas que trabajan juntas en un proyecto o equipo. Se crean con recursos que comparten los miembros del grupo, incluidos los siguientes:

• Conversaciones de Outlook
• Calendario de Outlook
• Archivos de SharePoint
• Bloc de notas de OneNote
• Sitio de grupo de SharePoint
• Planes de Planner
• Administración de dispositivos de Intune

El siguiente objeto JSON muestra una representación de ejemplo de un grupo cuando se llama a la API de grupos de 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"
}

Para obtener más información sobre los grupos de Microsoft 365, consulte Introducción a los grupos de Microsoft 365 en Microsoft Graph.

Configuración para grupos de Microsoft 365

Además de configurar las propiedades de grupo estándar, también puede configurar los siguientes valores para los grupos de Microsoft 365.

• Expiración del grupo
• Configuración de grupo, como si el grupo puede tener invitados como miembros, quién puede crear grupos, palabras permitidas en nombres de grupo, etc.

Grupos de seguridad y grupos de seguridad con correo habilitado

Los grupos de seguridad están diseñados para controlar el acceso de los usuarios a los recursos. Al comprobar si un usuario es miembro de un grupo de seguridad, la aplicación puede tomar decisiones de autorización cuando el usuario intenta obtener acceso a algunos recursos seguros de la aplicación. Los grupos de seguridad pueden tener usuarios, otros grupos de seguridad, dispositivos y entidades de servicio como miembros.

Los grupos de seguridad habilitados para correo se usan de la misma manera que los grupos de seguridad, pero se pueden usar para enviar correos electrónicos a los miembros del grupo. Los grupos de seguridad habilitados para correo no se pueden crear ni actualizar a través de la API; en su lugar, son de solo lectura. Obtenga más información en el artículo Administrar grupos de seguridad de correo en Exchange.

El siguiente objeto JSON muestra una representación de ejemplo de un grupo de seguridad al llamar a la API de grupos de 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
}

Pertenencia a grupos

La pertenencia a grupos puede asignarse estáticamente o ser dinámica. No todos los tipos de objetos pueden ser miembros de Microsoft 365 y grupos de seguridad.

En la tabla siguiente se muestran los tipos de miembros que se pueden agregar a grupos de seguridad o grupos de Microsoft 365.

Tipo de objeto	Miembro de grupo de seguridad	Miembro del grupo Microsoft 365
User
Grupo de seguridad
Grupo de Microsoft 365
Dispositivo
Servicio principal
Contacto organizacional

Pertenencia dinámica

Microsoft 365 y los grupos de seguridad pueden tener reglas de pertenencia dinámicas que agregan o quitan automáticamente miembros del grupo en función de las propiedades de la entidad de seguridad. Por ejemplo, un grupo de "Empleados de marketing" puede definir una regla de pertenencia dinámica por la que solo los usuarios con su propiedad de departamento establecida en "Marketing" pueden ser miembros del grupo. En este caso, los usuarios que abandonan el departamento se quitan automáticamente del grupo.

Solo se admiten usuarios y dispositivos como miembros de grupos de pertenencia dinámica. Puede crear un grupo de pertenencia dinámica para dispositivos o usuarios, pero no ambos.

Las reglas de pertenencia dinámica se especifican a través de la propiedad membershipRule durante la creación del grupo. Una sola expresión sigue esta sintaxis: Property Operator Value.

• Property Se define siguiendo esta sintaxis: object.property. Por ejemplo user.department o device.accountEnabled.
• La sintaxis de regla admite varios operadores. Para obtener más información, vea Operadores de expresiones admitidos.
• Un Value valor de tipo String debe estar entre comillas dobles ("). Debe usar una barra diagonal inversa para escapar las comillas dobles entre comillas dobles. Este requisito no se aplica al usar el generador de reglas en el Centro de administración Microsoft Entra porque la expresión no está entre comillas dobles.

En el ejemplo siguiente se muestra una regla completa.

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

Puede combinar varias expresiones en una regla mediante los andoperadores , ory not .

La propiedad groupType también debe incluir el "DynamicMembership" valor en la colección. La regla de pertenencia dinámica se puede activar o desactivar a través de la propiedad membershipRuleProcessingState. Puede actualizar un grupo con pertenencia asignada para que tenga una pertenencia dinámica.

En la solicitud de ejemplo siguiente se crea un nuevo grupo de Microsoft 365 que solo puede incluir empleados del departamento de 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);

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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"\
}\
'

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Ir

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)

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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);

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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);

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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();

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del 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)

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

La solicitud devuelve un 201 Created código de respuesta y el objeto de grupo recién creado en el cuerpo de la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

Para más información sobre la formulación de reglas de pertenencia, consulte Reglas de pertenencia dinámica para grupos en Microsoft Entra ID.

Nota:

Las reglas de pertenencia dinámica requieren que el inquilino tenga al menos una licencia Microsoft Entra ID P1 para cada usuario único que sea miembro de uno o varios grupos dinámicos.

Otros tipos de grupos

Los grupos de Microsoft 365 en Yammer se usan para facilitar la colaboración de usuarios a través de publicaciones de Yammer. Este tipo de grupo se puede devolver a través de una solicitud de lectura, pero no se puede obtener acceso a sus publicaciones mediante la API. Cuando se habilitan las publicaciones y las fuentes de conversaciones de Yammer en un grupo, se deshabilitan las conversaciones de grupo de Microsoft 365 predeterminado. Para más información, vea los documentos de la API para desarrolladores de Yammer.

Limitaciones de búsqueda de grupos para usuarios invitados en las organizaciones

Las funcionalidades de búsqueda de grupos permiten a la aplicación buscar grupos en el directorio de una organización realizando consultas en el /groups recurso (por ejemplo, https://graph.microsoft.com/v1.0/groups). Tanto los administradores como los usuarios que son miembros tienen esta funcionalidad; sin embargo, los usuarios invitados no.

Si el usuario que ha iniciado sesión es un usuario invitado, en función de los permisos que se hayan concedido a una aplicación, puede leer el perfil de un grupo específico (por ejemplo, https://graph.microsoft.com/v1.0/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc), pero no puede realizar consultas en el recurso /groups que devuelvan potencialmente más de un solo recurso.

Con los permisos adecuados, la aplicación puede leer los perfiles de grupos que obtiene siguiendo los vínculos de las propiedades de navegación, por ejemplo, /groups/{id}/members.

Para obtener más información sobre lo que los usuarios invitados pueden hacer con los grupos, consulte Comparar permisos predeterminados de miembros e invitados.

Licencias basadas en grupos

Puede usar licencias basadas en grupos para asignar una o varias licencias de productos a un grupo de Microsoft Entra. Microsoft Entra ID garantiza que las licencias se asignan a todos los miembros del grupo. Si se unen nuevos miembros al grupo se les asignarán las licencias adecuadas. Cuando abandonen el grupo, se quitarán esas licencias. La característica solo puede usarse con grupos de seguridad y grupos de Microsoft 365 con securityEnabled=TRUE. Para obtener más información sobre las licencias basadas en grupos, consulte ¿Qué es las licencias basadas en grupos en Microsoft Entra ID?.

Casos de uso comunes

Con Microsoft Graph, puede realizar las siguientes operaciones comunes en grupos.

Casos de uso	Recursos de REST	Ver también
Crear grupos, administrar características de grupo
Crear grupos, obtener grupos existentes, actualizar las propiedades de los grupos y eliminar grupos. Actualmente, solo se pueden crear mediante la API grupos de seguridad y grupos de Outlook.	group	Crear grupos Enumerar grupos Actualizar grupos Eliminar grupos
Administrar pertenencia a grupos
Enumerar los miembros de un grupo y agregar o quitar miembros.	user group	Enumerar miembros Agregar miembro Eliminar miembro
Determinar si un usuario es miembro de un grupo y obtener todos los grupos a los que pertenece el usuario.	user grupo servicePrincipal orgContact	Comprobar grupos de miembro Obtener grupos de miembro
Enumerar los propietarios de un grupo y agregar o quitar propietarios.	user group	Enumerar propietarios Agregar miembro Eliminar miembro