Introducción a los permisos de Microsoft Graph
Antes de que el Plataforma de identidad de Microsoft pueda autorizar a la aplicación a acceder a los datos en la nube de Microsoft, se deben conceder a la aplicación los privilegios que necesita. De forma similar, antes de que el Plataforma de identidad de Microsoft pueda autorizar a la aplicación a acceder a los datos a través de Microsoft Graph, se deben 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 rol (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 de RBAC.
En este artículo se presentan los permisos de Microsoft Graph y se proporcionan instrucciones para usarlos. Para ver la lista completa de permisos que expone Microsoft Graph, consulte la referencia de permisos de Microsoft Graph.
Para obtener más información sobre cómo funcionan los permisos, watch el siguiente vídeo.
Tipos de permisos
Microsoft Graph admite dos escenarios de acceso, el acceso delegado y el acceso solo a la 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 solo a la aplicación, la aplicación llama a Microsoft Graph con su propia identidad, sin que un usuario haya iniciado sesión.
Para admitir estos escenarios de acceso, Microsoft Graph expone permisos delegados y permisos de aplicación.
Permisos delegados
Los permisos delegados, también denominados ámbitos, se usan en el escenario de acceso delegado. Son permisos que 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 inició sesión no pudo acceder.
Por ejemplo, a una aplicación se le ha concedido el permiso delegado Files.Read.All 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 puede tener acceso a los archivos porque tiene permisos a través de una de las siguientes maneras:
- Tom creó o posee los archivos.
- Los archivos se compartieron directamente con Tom o se compartieron indirectamente a través de una pertenencia a un equipo o grupo.
- A Tom se le han concedido permisos a través de un sistema RBAC compatible.
Por lo tanto, en un escenario delegado, los privilegios que una aplicación tiene para actuar en nombre de un usuario viene determinado 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 podría permitir a los usuarios iniciar sesión con sus cuentas personales de Microsoft, como Outlook.com, cuentas profesionales o educativas, o permitir 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 que son válidos para cuentas personales de Microsoft.
Cuando un usuario inicia sesión en una aplicación, se le da la oportunidad de dar su consentimiento a los permisos delegados o, en algunos casos, a un administrador. Si conceden consentimiento, la aplicación puede acceder a recursos y API dentro de los límites de los permisos del usuario.
Nota:
Los permisos concedidos a través de Microsoft Entra roles integrados no limitan la aplicación a llamar solo a las API de Microsoft Graph.
Permisos de la aplicación
Los permisos de aplicación, también denominados roles de aplicación, se usan en el escenario de acceso de solo aplicación, sin que haya un usuario que haya iniciado sesión. La aplicación puede acceder a los datos a los que está asociado el permiso. Por ejemplo, una aplicación con el permiso de aplicación Files.Read.All puede leer cualquier archivo de la organización.
En el caso de las aplicaciones que acceden a recursos y API sin un usuario que ha iniciado sesión, un administrador da su consentimiento a los permisos de aplicación cuando la aplicación se instala en el inquilino o a través de la Centro de administración Microsoft Entra. Solo el administrador de roles con privilegios y el administrador global pueden dar su consentimiento a los permisos de la aplicación.
Además de tener asignados permisos de aplicación de Microsoft Graph, también se pueden conceder los privilegios que necesita a una aplicación mediante una de las condiciones siguientes:
- Cuando a la aplicación se le asigna la propiedad del recurso que pretende administrar.
- Cuando se asignan permisos a la aplicación a través de un sistema RBAC o roles administrativos personalizados.
Nota:
Los permisos concedidos a través de Microsoft Entra roles integrados no limitan la aplicación a llamar solo a las API de Microsoft Graph.
Comparación de permisos delegados y de aplicación
| Categoría | Permisos delegados | Permisos de aplicación |
|---|---|---|
| Tipos de aplicaciones | Aplicación web / Móvil / Aplicación de página única (SPA) | Web o Daemon |
| Contexto de acceso | Obtener acceso en nombre de un usuario | Obtener acceso sin un usuario |
| ¿Quién puede dar su consentimiento? | Solo el administrador puede dar el consentimiento | |
| Otros nombres | ||
| Resultado del consentimiento | oAuth2PermissionGrant (objeto) | appRoleAssignment (objeto) |
| Tipos de signInAudience admitidos | AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount PersonalMicrosoftAccount |
AzureADMyOrg AzureADMultipleOrgs AzureADandPersonalMicrosoftAccount |
En la imagen siguiente se muestran los privilegios de una aplicación en escenarios de acceso delegado frente a solo aplicación.
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 se denominan en el patrón siguiente:
{resource}. {operation}. {constraint}
| Valor | Descripción | Ejemplos |
|---|---|---|
{resource} |
Hace referencia a un recurso de Microsoft Graph al que el permiso permite el acceso. Por ejemplo, el user recurso. |
User, Application o Group |
{operation} |
Hace referencia a las operaciones de Microsoft Graph API que se permiten en los datos expuestos por el recurso. Por ejemplo, Read solo para operaciones de lectura o ReadWrite para operaciones de lectura, creación, actualización y eliminación. |
Read, ReadBasic, ReadWrite, Create, Manageo Migrate |
{constraint} |
Determina la posible extensión del acceso que una aplicación tiene dentro del directorio. Es posible que este valor no se declare explícitamente. Cuando no se declara, la restricción predeterminada se limita a los datos propiedad del usuario que ha iniciado sesión. |
All, AppFolder, OwnedBy, Selected, Shared, Hidden |
Ejemplos:
- User.Read : permite que la aplicación lea 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 posee.
- Group.Create : permite a la aplicación crear grupos nuevos, pero no modificarlos ni eliminarlos.
- Member.Read.Hidden : permite que la aplicación lea 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 permite conceder acceso con á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 proporcionen acceso a la aplicación a todas las instancias del tipo de recurso de todo el inquilino.
Los permisos de RSC también están disponibles para su consentimiento y solo son compatibles con un subconjunto de características disponibles a través de Microsoft Graph, como Teams, chats y mensajes. Obtenga más información sobre los permisos de RSC o descubra la lista completa de permisos de 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, se devuelven objetos de ese tipo pero con información limitada, por ejemplo, solo se pueden devolver el tipo de objeto y el identificador y otras propiedades como null. Se devuelve información completa para los tipos de objeto que la aplicación tiene permisos para leer.
Este principio se aplica a todas las relaciones que son de tipo directoryObject . Algunos ejemplos son /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 GroupMember.Read.All con privilegios mínimos 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 otras propiedades se indican como null. Para esta API:
- Para leer las propiedades básicas de los miembros de un grupo que son usuarios, la aplicación necesita al menos el permiso User.ReadBasic.All .
- Para leer las propiedades básicas de los miembros de un grupo que son grupos, la aplicación necesita al menos el permiso GroupMember.Read.All .
- Para leer las propiedades básicas de los miembros de un grupo que son dispositivos, la aplicación necesita al menos el permiso Device.Read.All , etc.
- Sin embargo, como alternativa a los permisos de nivel de recurso individuales, se puede asignar a la aplicación al menos el permiso Directory.Read.All para leer todas las propiedades de todos los tipos de miembros.
Ejemplo
Solicitud
GET https://graph.microsoft.com/v1.0/groups/{id}/members
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 pormenorizados permiten aplicar el principio de privilegios mínimos al asignar y conceder permisos a una aplicación, al conceder a la aplicación el permiso mínimo que necesita para la operación.
Considere los siguientes ejemplos:
- Una aplicación solo necesita leer la información de 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. Conceder a la aplicación el permiso User.ReadWrite hace que tenga privilegios excesivos porque la aplicación no necesita actualizar el perfil del usuario.
- Una aplicación debe leer los grupos del inquilino sin que un usuario 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 que un usuario haya iniciado sesión.
- Una aplicación debe leer o escribir en un calendario del usuario que ha iniciado sesión. La aplicación administra trabajos dinámicos y se sincroniza desde el calendario de Outlook del usuario para mantener la aplicación actualizada para programar trabajos para el usuario. Aunque la obtención de los datos de calendario del usuario requiere Calendars.Read, actualizar el calendario con trabajos programados requiere un permiso con privilegios más elevados, Calendars.ReadWrite. En este caso, la aplicación debe solicitar Calendars.ReadWrite.
Conceder a una aplicación más privilegios de los que necesita es una práctica de seguridad deficiente que aumenta la superficie expuesta a ataques de la aplicación y la expone a accesos no autorizados e imprevistos a datos o operaciones. Además, solicitar más permisos de los necesarios puede hacer que los usuarios se abstuvieran 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 Mejora de la seguridad con el principio de privilegios mínimos y Creación de aplicaciones que protegen la identidad mediante permisos y consentimiento.
Permisos para usar con precaución
Algunos permisos de Microsoft Graph conceden acceso a una gama más amplia de datos o operaciones que otros. Use estos permisos con precaución. Por ejemplo, el permiso Directory.AccessAsUser.All es el permiso delegado con privilegios más alto que concede acceso a casi todas las operaciones de API en Microsoft Entra ID. El permiso Directory.ReadWrite.All es el segundo en la clasificación de privilegios. Directory.Read.All es el permiso de solo lectura con privilegios más alto para Microsoft Entra ID recursos. Estos permisos se deben usar con precaución y solo cuando sea necesario. Use siempre permisos de opciones con privilegios inferiores en su lugar.
En la documentación de referencia de API relacionada con Microsoft Entra ID recursos, algunos de estos permisos con privilegios superiores podrían 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 privilegios más alto en Microsoft Entra ID. En la documentación de referencia de API, este rol se excluye intencionadamente de la lista de roles admitidos para acceder a la API en favor de los roles con privilegios inferiores.
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 dar su consentimiento. Estos límites dependen del signInAudience valor de una aplicación, que se muestra en el manifiesto de la aplicación.
| signInAudience | Usuarios permitidos | Permisos máximos que la aplicación puede solicitar | Permisos máximos Microsoft Graph que la aplicación puede solicitar | Permisos máximos que se pueden consentir en una sola solicitud |
|---|---|---|---|---|
| AzureADMyOrg | Usuarios de la organización donde está registrada la aplicación | 400 | 400 | Unos 155 permisos delegados y unos 300 permisos de aplicación |
| AzureADMultipleOrgs | Usuarios de cualquier organización Microsoft Entra | 400 | 400 | Unos 155 permisos delegados y unos 300 permisos de aplicación |
| PersonalMicrosoftAccount | Usuarios consumidores (como cuentas de Outlook.com o Live.com) | 30 | 30 | 30 |
| AzureADandPersonalMicrosoftAccount | Usuarios consumidores y usuarios de cualquier organización Microsoft Entra | 30 | 30 | 30 |
Recuperar identificadores de permiso a través de Microsoft Graph
Para establecer permisos mediante la CLI de Azure, PowerShell o la 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 get servicePrincipal API 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 de la aplicación, delegados y específicos del recurso, respectivamente.