Información general sobre los permisos de Microsoft Graph

Para que la Plataforma de identidad de Microsoft pueda autorizar a su aplicación a acceder a los datos de la nube de Microsoft, debe conceder a la aplicación los privilegios que necesita. Del mismo modo, antes de que la Plataforma de identidad de Microsoft pueda autorizar a su aplicación a acceder a los datos a través de Microsoft Graph, debe conceder a la aplicación los privilegios que necesita.

Una manera de conceder a una aplicación los privilegios que necesita para acceder a los datos y trabajar con ellos a través de Microsoft Graph es asignarle permisos de Microsoft Graph. Otra manera es a través de sistemas de control de acceso basado en roles (RBAC), como Microsoft Entra RBAC. En algunos casos, el acceso a los datos a través de las API de Microsoft Graph puede requerir permisos de Microsoft Graph y permisos RBAC.

En este artículo se presentan los permisos de Microsoft Graph y se proporciona orientación sobre cómo usarlos. Para ver la lista completa de permisos que expone Microsoft Graph, vea la referencia de permisos de Microsoft Graph.

Para obtener más información sobre cómo funcionan los permisos, vea el siguiente vídeo.

Tipos de permisos

Microsoft Graph admite dos escenarios de acceso: acceso delegado y acceso solo de aplicación. En el acceso delegado, la aplicación llama a Microsoft Graph en nombre de un usuario que ha iniciado sesión. En el acceso de solo aplicación, la aplicación llama a Microsoft Graph con su propia identidad, sin un usuario que haya iniciado sesión.

Para admitir estos escenarios de acceso, Microsoft Graph expone los permisos delegados y los permisos de aplicación.

Permisos delegados

Los permisos delegados, también denominados ámbitos, funcionan en el escenario de acceso delegado. Estos permisos permiten que la aplicación actúe en nombre de un usuario que ha iniciado sesión. Sin embargo, la aplicación no puede acceder a nada a lo que el usuario que ha iniciado sesión no haya podido acceder.

Por ejemplo, una aplicación obtiene los Files. Read.All permiso delegado en nombre de Tom, un usuario. La aplicación solo puede leer todos los archivos de la organización a los que Tom ya puede acceder. Tom podría acceder a los archivos porque tiene permisos a través de una de las siguientes maneras:

• Tom creó o es el propietario de los archivos.
• Los archivos se compartieron directamente con Tom o indirectamente a través de miembros de un equipo o grupo.
• A Tom se le han concedido permisos a través de un sistema RBAC admitido.

Por lo tanto, en un escenario delegado, los privilegios que tiene una aplicación para actuar en nombre de un usuario vienen determinados por los permisos de Microsoft Graph que se han concedido a la aplicación y los propios permisos del usuario.

En un escenario de acceso delegado, una aplicación puede permitir que los usuarios inicien sesión con sus cuentas personales de Microsoft, como cuentas Outlook.com, profesionales o educativas, o ambos tipos de cuenta. Todos los permisos delegados son válidos para cuentas profesionales o educativas, pero no todos son válidos para cuentas personales de Microsoft. Use la referencia de permisos de Microsoft Graph para identificar los permisos delegados válidos para las cuentas personales de Microsoft.

Cuando un usuario inicia sesión en una aplicación, él o, en algunos casos, un administrador, tienen la oportunidad de dar su consentimiento a los permisos delegados. Si conceden consentimiento, la aplicación puede acceder a recursos y API dentro de los límites de los permisos del usuario.

Permisos de la aplicación

Los permisos de aplicación, también denominados roles de aplicación, funcionan en el escenario de acceso de solo aplicación, sin la presencia de un usuario que haya iniciado sesión. La aplicación puede acceder a cualquier dato al que esté asociado el permiso. Por ejemplo, una aplicación concedió los Files. El permiso de aplicación Read.All puede leer cualquier archivo de la organización.

Con el permiso de la aplicación User.ReadWrite.All , una aplicación puede actualizar muchas de las propiedades de usuario grabables compatibles con Microsoft Graph, incluidas las de los usuarios a los que se les han asignado roles de administrador con privilegios.

Los permisos de aplicación son altamente privilegiados porque permiten a las aplicaciones acceder a los recursos y modificarlos sin necesidad de un usuario que haya iniciado sesión. Desde una perspectiva con privilegios mínimos, el modelo de permisos delegados es el enfoque recomendado siempre que cumpla los requisitos de la aplicación.

En el caso de las aplicaciones que acceden a recursos y API sin un usuario que haya iniciado sesión, un administrador da su consentimiento a los permisos de la aplicación cuando la aplicación se instala en el inquilino o a través del Centro de administración de Microsoft Entra de Microsoft Entra. Solo el administrador de roles con privilegios y el administrador global pueden dar su consentimiento a los permisos de aplicación.

Además de tener asignados permisos de aplicación de Microsoft Graph, una aplicación también puede recibir los privilegios que necesita mediante una de las siguientes condiciones:

• Cuando se asigna la propiedad del recurso que pretende administrar a la aplicación.
• Cuando se asignan permisos a la aplicación mediante un sistema RBAC o roles administrativos personalizados.

Comparación de permisos delegados y de aplicación

En la imagen siguiente se muestran los privilegios de una aplicación en escenarios de acceso delegado frente a acceso solo de aplicación.

Procedimientos recomendados para seleccionar tipos de permisos para el registro del agente del conector

Los agentes del conector de Microsoft Graph se ejecutan como servicios en segundo plano y requieren permisos de aplicación de Microsoft Graph.

Los permisos delegados no se admiten para el registro del agente del conector y provocan errores de registro, incluso cuando los permisos aparecen configurados correctamente.

Solicite los permisos de aplicación con privilegios mínimos necesarios para el escenario del conector y asegúrese de que se otorga el consentimiento del administrador de todo el inquilino .

Patrón de nomenclatura de permisos

Microsoft Graph expone permisos granulares que le ayudan a controlar el acceso que las aplicaciones tienen a los recursos de Microsoft Graph, como usuarios, grupos y correo. Estos permisos siguen el patrón de nomenclatura:

{resource}. {operación}. {restricción}

Ejemplos:

• User.Read : permite a la aplicación leer información sobre el usuario que ha iniciado sesión.
• Application.ReadWrite.All : permite que la aplicación administre todas las aplicaciones del inquilino.
• Application.ReadWrite.OwnedBy : permite que la aplicación administre solo las aplicaciones que crea o que posee.
• Group.Create - Permite a la aplicación crear nuevos grupos, pero no modificarlos ni eliminarlos.
• Member.Read.Hidden - Permite que la aplicación lea las pertenencias ocultas.

Para obtener la lista completa de permisos expuestos por Microsoft Graph, consulte la referencia de permisos de Microsoft Graph.

Permisos de consentimiento específico de recursos (RSC)

RSC es un marco de autorización que concede acceso de ámbito a los datos expuestos por un recurso. A través de RSC, un usuario autorizado puede conceder a una aplicación acceso a los datos de una instancia específica de un tipo de recurso. No es necesario que concedan acceso de aplicación a todas las instancias del tipo de recurso en todo el inquilino.

Los permisos RSC también están disponibles para consentimiento y solo son compatibles con un subconjunto de características disponibles a través de Microsoft Graph, como Teams, chats y mensajes. Para obtener más información, consulte Permisos RSC y la lista completa de permisos RSC disponibles.

Información limitada devuelta por objetos miembro inaccesibles

Los objetos contenedores, como los grupos, admiten distintos tipos de miembros; por ejemplo, usuarios y dispositivos. Cuando una aplicación con los privilegios adecuados consulta la pertenencia de un objeto contenedor, recibe una 200 OK respuesta y una colección de objetos. Sin embargo, si la aplicación no tiene los permisos para leer un determinado tipo de objeto en el contenedor, recibe objetos de ese tipo, pero con información limitada. Por ejemplo, puede que solo se devuelvan el tipo de objeto y el identificador y las demás propiedades se indican como null. La aplicación recibe información completa para los tipos de objeto para los que tiene permisos de lectura.

Este principio se aplica a todas las relaciones de tipo directoryObject . Los ejemplos incluyen /groups/{id}/members, /users/{id}/memberOfy me/ownedObjects.

Por ejemplo, un grupo puede tener usuarios, grupos, aplicaciones, entidades de servicio, dispositivos y contactos como miembros. A una aplicación se le concede el permiso con privilegios mínimos GroupMember.Read.All para enumerar los miembros del grupo. En el objeto de respuesta, solo se rellenan las propiedades id y @odata.type para todos los miembros que se devuelven. Las demás propiedades se indican como null. Para esta API y para devolver más información para los miembros del grupo, la aplicación necesita los siguientes permisos adicionales:

• Para leer las propiedades básicas de los miembros de un grupo que son usuarios, User.ReadBasic.All es el permiso con privilegios mínimos.
• Para leer las propiedades básicas de los miembros de un grupo que son grupos, GroupMember.Read.All es el permiso con privilegios mínimos.
• Para leer las propiedades básicas de los miembros de un grupo que son dispositivos, Device.Read.All es el permiso con privilegios mínimos.
• Para leer las propiedades básicas de los miembros de un grupo que son entidades de servicio, Application.Read.All es el permiso con privilegios mínimos.
• Según el principio de privilegios mínimos, use los permisos anteriores según corresponda para su aplicación; sin embargo, como alternativa a los permisos de nivel de recursos individuales, asigne a la aplicación el permiso Directory.Read.All para leer todas las propiedades de todos los tipos de miembro.

Ejemplo

Solicitud

GET https://graph.microsoft.com/v1.0/groups/{id}/members

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].Members.GetAsync();

// 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"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
members, err := graphClient.Groups().ByGroupId("group-id").Members().Get(context.Background(), nil)

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

DirectoryObjectCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().get();

const options = {
	authProvider,
};

const client = Client.init(options);

let members = await client.api('/groups/{id}/members')
	.get();

<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->get()->wait();

Import-Module Microsoft.Graph.Groups

Get-MgGroupMember -GroupId $groupId

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.groups.by_group_id('group-id').members.get()

Respuesta

El siguiente objeto es un ejemplo de la respuesta:

{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#directoryObjects",
    "value":[
        {
            "@odata.type":"#microsoft.graph.user",
            "id":"69d035a3-29c9-469f-809d-d21a4ae69e65",
            "displayName":"Adele Vance",
            "createdDateTime":"2019-09-18T09:06:51Z",
        },
        {
            "@odata.type":"#microsoft.graph.group",
            "id":"c43a7cc9-2d95-44b6-bf6a-6392e41949b4",
            "displayName":"All Company",
            "description":null,
            "createdDateTime":"2019-10-24T01:34:35Z"
        },
        {
            "@odata.type":"#microsoft.graph.device",
            "id": "d282309e-f91d-43b6-badb-9e68aa4b4fc8",
            "accountEnabled":null,
            "deviceId":null,
            "displayName":null,
            "operatingSystem":null,
            "operatingSystemVersion":null
        }
    ]
}

Procedimientos recomendados para usar permisos de Microsoft Graph

Microsoft Graph expone permisos granulares que permiten a una aplicación solicitar solo los permisos que necesita para funcionar. Los permisos granulares le permiten aplicar el principio de privilegios mínimos al asignar y conceder permisos a una aplicación. Conceda a la aplicación el permiso mínimo que necesita para la operación.

Considere los siguientes ejemplos:

• Una aplicación necesita leer la información del perfil del usuario que ha iniciado sesión. La aplicación solo requiere el permiso User.Read , que es el permiso con privilegios mínimos para acceder a la información del usuario que ha iniciado sesión. Al conceder a la aplicación el permiso User.ReadWrite se le concede un exceso de privilegios porque la aplicación no necesita actualizar el perfil del usuario.
• Una aplicación necesita leer los grupos del inquilino sin un usuario que haya iniciado sesión. La aplicación solo requiere el permiso de aplicación GroupMember.Read.All , que es el permiso con privilegios mínimos para leer grupos en el inquilino sin un usuario que haya iniciado sesión.
• Una aplicación necesita leer o escribir en un calendario del usuario que ha iniciado sesión. La aplicación administra los trabajos dinámicos y se sincroniza desde el calendario de Outlook del usuario para mantener la aplicación actualizada y programar trabajos para el usuario. Aunque la obtención de los datos del calendario del usuario requiere Calendars.Read, la actualización del calendario con trabajos programados requiere un permiso con privilegios mayores, Calendars.ReadWrite. En este caso, la aplicación debe solicitar Calendars.ReadWrite.

Otorgar a una aplicación más privilegios de los que necesita es una práctica de seguridad deficiente. Aumenta la exposición de la aplicación a accesos no autorizados e involuntarios a datos u operaciones. Además, solicitar más permisos de los necesarios puede hacer que los usuarios se abstengan de dar su consentimiento a una aplicación, lo que afecta a la adopción y el uso de una aplicación.

Aplique el principio de privilegios mínimos al asignar y conceder permisos de Microsoft Graph a una aplicación. Para obtener más información, consulte Mejorar la seguridad con el principio de privilegios mínimos y Creación de aplicaciones que protejan la identidad mediante permisos y consentimiento.

Permisos de uso con precaución

Algunos permisos de Microsoft Graph conceden acceso a una gama más amplia de datos u operaciones que otros. Use estos permisos con precaución. Por ejemplo, el permiso Directory.AccessAsUser.All es el permiso delegado con privilegios más altos que concede acceso a casi todas las operaciones de API en Microsoft Entra ID. El permiso Directory.ReadWrite.All ocupa el segundo lugar en la clasificación de privilegios. Directory.Read.All es el permiso de solo lectura con privilegios más altos para los recursos de Microsoft Entra ID. Use estos permisos con precaución y solo cuando sea necesario. En su lugar, use siempre permisos de opciones con privilegios menores.

En la documentación de referencia de la API relacionada con los recursos de Microsoft Entra ID, algunos de estos permisos con privilegios superiores pueden excluirse intencionadamente de la tabla de permisos admitidos para acceder a la API.

Además, el rol de administrador global es el rol integrado con mayores privilegios en Microsoft Entra ID. En la documentación de referencia de la API, este rol se excluye intencionadamente de la lista de roles que admiten el acceso a la API en favor de los roles con privilegios menores.

Límites de permisos solicitados por aplicación

Microsoft Entra ID limita el número de permisos que una aplicación cliente puede solicitar y consentir. Estos límites dependen del valor de signInAudience una aplicación, que se muestra en el manifiesto de la aplicación.

Recuperar identificadores de permisos a través de Microsoft Graph

Para establecer permisos mediante la CLI de Azure, PowerShell o infraestructura como marcos de código, es posible que necesite el identificador del permiso que desea usar en lugar del nombre. La referencia de permisos enumera los identificadores de todos los permisos de Microsoft Graph. Como alternativa, puede leer información sobre todos los permisos de Microsoft Graph mediante programación a través de la API Get servicePrincipal en Microsoft Graph. En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')?$select=id,appId,displayName,appRoles,oauth2PermissionScopes,resourceSpecificApplicationPermissions

Los objetos appRoles, oauth2PermissionScopes y resourceSpecificApplicationPermissions almacenan los permisos de consentimiento específicos de la aplicación, delegados y específicos del recurso, respectivamente.

Contenido relacionado

• Referencia de permisos de Microsoft Graph.
• Información general sobre el control de acceso basado en roles en Microsoft Entra ID.
• Descripción del acceso delegado