Trabajar con grupos en Microsoft Graph

Artículo
05/23/2024

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 el tipo de recurso de grupo y sus API asociadas para crear y administrar diferentes tipos de grupos y funcionalidad de grupo.

Nota:

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.
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ámica que no se pueden administrar ni recuperar a través de Microsoft Graph.

En Microsoft Graph, el tipo de grupo se puede identificar mediante la configuración de sus propiedades groupTypes, mailEnabled y securityEnabled . En la tabla siguiente se indica cómo diferenciar los grupos por su configuración y si los tipos de grupo se pueden administrar a través de las API de grupos de Microsoft Graph.

Tipo	groupTypes	mailEnabled	securityEnabled	Creación y administración a través de las 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; solo lectura a través de Microsoft Graph
Grupos de distribución	`[]`	`true`	`false`	No; solo lectura a través de Microsoft Graph

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

Para más información sobre los grupos de Microsoft 365 y las experiencias de administrador, vea Obtenga más información sobre los grupos de Microsoft 365.

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. Para obtener más información, consulte Administrar grupos de seguridad habilitados para correo.

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.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 groupTypes también debe incluir el "DynamicMembership" valor de 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.

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


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

// Dependencies
using Microsoft.Graph.Beta.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);

Importante

Los SDK de Microsoft Graph usan la versión v1.0 de la API de manera predeterminada y no admiten todos los tipos, propiedades y API disponibles en la versión beta. Para obtener más información sobre cómo acceder a la API beta con el SDK, consulte Uso de los SDK de Microsoft Graph con la API beta.

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.



mgc-beta 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"\
}\
'

Importante

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.



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

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-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)

Importante

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.


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

Importante

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.


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')
	.version('beta')
	.post(group);

Importante

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
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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();

Importante

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.


Import-Module Microsoft.Graph.Beta.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-MgBetaGroup -BodyParameter $params

Importante

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.


from msgraph_beta import GraphServiceClient
from msgraph_beta.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)

Importante

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

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.

Configuración adicional para la seguridad y los grupos de Microsoft 365

Además de configurar las propiedades en el recurso de grupo, también puede configurar los siguientes valores para los grupos.

Configuración	Se aplica a
Expiración del grupo	Grupos de Microsoft 365
Configuración de grupo, como si el grupo puede tener invitados como miembros, palabras permitidas en nombres de grupo, quién puede crear grupos, etc.	Grupos de Microsoft 365
Configuración para sincronizar grupos locales con la nube, como si la escritura diferida está habilitada	Seguridad y grupos de Microsoft 365

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/beta/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/beta/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, y las licencias las heredan los miembros del grupo y los miembros nuevos las heredan automáticamente. Cuando los miembros abandonan el grupo, se quitan esas licencias. La característica solo se puede usar con grupos de seguridad y grupos de Microsoft 365 que tengan securityEnabled establecido en 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?.

Propiedades almacenadas fuera del almacén de datos principal

Aunque los datos de recursos de grupo se almacenan principalmente en Microsoft Entra ID, algunas de sus propiedades, como autoSubscribeNewMembers y allowExternalSenders, se almacenan en Microsoft Exchange. En la mayoría de los casos, no puede especificar estas propiedades en el mismo Create o en el cuerpo de la solicitud de actualización que otras propiedades de grupo.

Las propiedades almacenadas fuera del almacén de datos principal tampoco se admiten como parte del seguimiento de cambios. Por lo tanto, un cambio en cualquiera de estas propiedades no da lugar a que un objeto aparezca en la respuesta de consulta delta.

Casos de uso comunes para la API de grupos en Microsoft Graph

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

Casos de uso	Operaciones de API
Crear grupos, administrar características de grupo
Crear grupos, obtener grupos existentes, actualizar las propiedades de los grupos y eliminar grupos.	Crear grupos Enumerar grupos Actualizar grupos Eliminar grupos Renovación de grupos que están a punto de expirar Restauración de grupos eliminados de Microsoft 365
Administración de la pertenencia a grupos y la propiedad
Enumerar los miembros de un grupo y agregar o quitar miembros.	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.	Comprobar grupos de miembro Obtener grupos de miembro
Enumerar los propietarios de un grupo y agregar o quitar propietarios.	Enumerar propietarios Agregar propietario Eliminar propietario
Funcionalidad de grupo para aplicaciones de Microsoft 365
Administración de conversaciones de grupo	Create, obtener o eliminar
Programar y administrar eventos de calendario en un calendario de grupo	Create, list, get, update, delete
Administración de cuadernos de OneNote para un grupo	Create, lista
Habilitación de un grupo de Microsoft para Microsoft Teams	Crear

roles de Microsoft Entra para administrar grupos

Para administrar grupos en escenarios delegados, se deben conceder a la aplicación los permisos adecuados y el usuario que ha iniciado sesión debe tener un rol de Microsoft Entra compatible.

Los siguientes roles de Microsoft Entra son los roles con privilegios mínimos para administrar todos los aspectos de los grupos a través de Microsoft Graph, excepto para los grupos a los que se pueden asignar roles. El rol con privilegios mínimos para administrar grupos a los que se pueden asignar roles es Administrador de roles con privilegios.

Escritores de directorios
Administrador de Grupos
Administrador de usuarios

Paso siguiente

Empezar a trabajar con grupos

Compartir a través de

Trabajar con grupos en Microsoft Graph

Tipos de grupo en Microsoft Entra ID y Microsoft Graph

Grupos de Microsoft 365

Grupos de seguridad y grupos de seguridad con correo habilitado

Pertenencia a grupos

Pertenencia dinámica

Otros tipos de grupos

Configuración adicional para la seguridad y los grupos de Microsoft 365

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

Licencias basadas en grupos

Propiedades almacenadas fuera del almacén de datos principal

Casos de uso comunes para la API de grupos en Microsoft Graph

roles de Microsoft Entra para administrar grupos

Paso siguiente

Comentarios

Comentarios

Recursos adicionales