Administración de grupos en Microsoft Graph

Los grupos de Microsoft Graph son contenedores para entidades de seguridad como usuarios, dispositivos o aplicaciones que comparten el acceso a los recursos. Facilitan la administración del acceso mediante la agrupación de entidades de seguridad en lugar de administrarlas individualmente.

El tipo de recurso de grupo de Microsoft Graph proporciona API para crear y administrar tipos de grupo admitidos y sus funcionalidades.

Nota:

• Solo puede crear grupos con cuentas profesionales o educativas. Las cuentas personales de Microsoft no admiten grupos.
• Todas las operaciones relacionadas con grupos de Microsoft Graph necesitan el consentimiento del administrador.

Tipos de grupos admitidos en Microsoft Graph

Microsoft Graph admite estos tipos de grupos:

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

Nota:

Los grupos de distribución dinámica no se admiten en Microsoft Graph.

En la tabla siguiente se muestra cómo identificar tipos de grupos mediante sus propiedades y si se pueden administrar mediante la API de grupos de Microsoft Graph. Los diferenciadores principales son los valores de las propiedades groupTypes, mailEnabled y securityEnabled de un grupo.

Tipo	groupTypes	mailEnabled	securityEnabled	Administrado a través de Microsoft Graph
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)
Grupos de distribución	[]	true	false	No (solo lectura)

Para obtener más información, consulte Comparación de grupos en Microsoft Entra ID.

Grupos de Microsoft 365

Grupos de Microsoft 365 están diseñadas para la colaboración y proporcionan acceso a recursos compartidos como:

• Conversaciones y calendarios de Outlook.
• Archivos de SharePoint y sitio de equipo.
• Bloc de notas de OneNote.
• Planner planes.
• Intune administración de dispositivos.

Este es un ejemplo de un grupo de Microsoft 365 en formato JSON:

HTTP/1.1 201 Created
Content-type: application/json

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",
    "displayName": "OutlookGroup101",
    "groupTypes": ["Unified"],
    "mailEnabled": true,
    "securityEnabled": false,
    "mail": "outlookgroup101@service.microsoft.com",
    "visibility": "Public"
}

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

Grupos de seguridad y grupos de seguridad con correo habilitado

Los grupos de seguridad controlan el acceso a los recursos. Pueden incluir usuarios, otros grupos, dispositivos y entidades de servicio.

Los grupos de seguridad habilitados para correo funcionan como grupos de seguridad, pero también permiten la comunicación por correo electrónico. Estos grupos son de solo lectura en Microsoft Graph. Para obtener más información, consulte Administrar grupos de seguridad habilitados para correo.

Ejemplo de un grupo de seguridad en formato JSON:

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.type": "#microsoft.graph.group",
    "id": "f87faa71-57a8-4c14-91f0-517f54645106",
    "displayName": "SecurityGroup101",
    "groupTypes": [],
    "mailEnabled": false,
    "securityEnabled": true
}

Pertenencia a grupos

Los grupos pueden tener pertenencias estáticas o dinámicas. La pertenencia dinámica usa reglas para agregar o quitar miembros automáticamente en función de sus propiedades. 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

La pertenencia dinámica significa que las entidades de seguridad se agregan o quitan del grupo en función de sus propiedades. Por ejemplo, se puede establecer un grupo para incluir a todos los usuarios en el departamento "Marketing". Cuando se agrega un usuario a ese departamento, se agregan automáticamente al grupo. De forma similar, si un usuario deja el departamento, se quita del grupo.

Solo los usuarios y dispositivos pueden ser miembros de un grupo dinámico. La pertenencia dinámica requiere una licencia Microsoft Entra ID P1 para cada usuario único de un grupo dinámico.

La regla de pertenencia se define mediante la sintaxis de la regla de grupo dinámica Microsoft Entra ID.

Ejemplo de una regla de pertenencia dinámica:

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

La pertenencia dinámica requiere el "DynamicMembership" valor de la propiedad groupTypes . La regla de pertenencia dinámica se puede activar o desactivar a través de la propiedad membershipRuleProcessingState. Puede actualizar un grupo de pertenencia estática a pertenencia dinámica.

Solicitud de ejemplo para crear un grupo dinámico de Microsoft 365:

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

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

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

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

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

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

Otras configuraciones de grupo

Puede configurar otras opciones para grupos, como:

Configuración	Se aplica a
Expiración del grupo	Grupos de Microsoft 365
Configuración de grupo	Grupos de Microsoft 365
Configuración de sincronización local	Seguridad y Grupos de Microsoft 365

Limitaciones de búsqueda de grupos para invitados en organizaciones

Las aplicaciones pueden buscar grupos en el directorio de una organización consultando el /groups recurso (por ejemplo, https://graph.microsoft.com/beta/groups). Esta funcionalidad está disponible para administradores y miembros, pero no para invitados.

Los invitados, en función de los permisos concedidos a la aplicación, pueden ver el perfil de un grupo específico (por ejemplo, https://graph.microsoft.com/beta/group/fc06287e-d082-4aab-9d5e-d6fd0ed7c8bc). Sin embargo, no pueden realizar consultas en el /groups recurso que devuelven varios resultados.

Por lo general, los miembros tienen acceso más amplio a los recursos del grupo, mientras que los invitados tienen permisos restringidos, lo que limita su acceso a determinadas características de grupo. Para obtener más información, vea Comparar permisos predeterminados de miembro e invitado.

Con los permisos adecuados, las aplicaciones pueden acceder a perfiles de grupo a través de propiedades de navegación, como /groups/{id}/members.

Licencias basadas en grupos

Las licencias basadas en grupos le permiten asignar una o varias licencias de producto a un grupo de Microsoft Entra. Los miembros del grupo, incluidos los miembros nuevos, heredan automáticamente las licencias. Cuando los miembros abandonan el grupo, sus licencias se quitan automáticamente. Esta característica solo está disponible para grupos de seguridad y Grupos de Microsoft 365 con securityEnabled establecido en true.

Para obtener más información, consulte ¿Qué es la licencia basada en grupos en Microsoft Entra ID?.

Propiedades almacenadas fuera del almacén de datos principal

La mayoría de los datos de recursos de grupo se almacenan en Microsoft Entra ID, pero algunas propiedades, como autoSubscribeNewMembers y allowExternalSenders, se almacenan en Microsoft Exchange. Estas propiedades no se pueden incluir en el mismo cuerpo de la solicitud Create o Update que otras propiedades del grupo.

Además, las propiedades almacenadas fuera del almacén de datos principal no se admiten para el seguimiento de cambios. Los cambios en estas propiedades no aparecen en las respuestas de consulta delta.

Las siguientes propiedades de grupo se almacenan fuera del almacén de datos principal:
accessType, allowExternalSenders, autoSubscribeNewMembers, cloudLicensing, hideFromAddressLists, hideFromOutlookClients, isFavorite, isSubscribedByMail, unseenConversationsCount, unseenCount, unseenMessagesCount, membershipRuleProcessingStatus, isArchived.

Casos de uso comunes para la API de grupos

La API de grupos de Microsoft Graph admite estas operaciones comunes:

Caso de uso	Operaciones de API
Crear y administrar grupos	Crear, enumerar, actualizar y eliminar
Administrar pertenencia a grupos	Enumerar miembros, agregar miembro y quitar miembro
Administración de la propiedad del grupo	Enumerar propietarios, agregar propietario y quitar propietario
Funcionalidad de grupo de Microsoft 365	Administración de conversaciones, eventos de calendario, cuadernos de OneNote y habilitación para Teams

roles de Microsoft Entra para administrar grupos

Para administrar grupos, el usuario que ha iniciado sesión debe tener los permisos de Microsoft Graph adecuados y tener asignado un rol de Microsoft Entra compatible.

Los roles con privilegios mínimos para administrar grupos son:

• Escritores de directorios
• Administrador de grupos
• Administrador de usuarios

Para obtener más información, consulte Roles con privilegios mínimos para administrar grupos.

Paso siguiente

Empezar a trabajar con grupos