Ámbitos de permiso | Conceptos de API Graph
Se aplica a: API Graph | Azure Active Directory (AD)
La API Graph expone los ámbitos de permiso de OAuth 2.0 que se usan para controlar el acceso de una aplicación a los datos de directorio del cliente. Como desarrollador, configura la aplicación con los ámbitos de permiso adecuados para el acceso que se requieren. Habitualmente, esto se realiza a través del Portal de Azure. Durante el inicio de sesión, los usuarios o los administradores tienen la oportunidad de consentir y permitir que la aplicación tenga acceso a sus datos de directorio con los ámbitos de permiso que se configuraron. Por este motivo, debería elegir los ámbitos de permiso que proporcionan el nivel de privilegio mínimo que necesita la aplicación. Para obtener más detalles sobre cómo configurar los permisos de la aplicación y acerca del proceso de consentimiento, consulte Integración de aplicaciones con Azure Active Directory.
Importante
Se recomienda encarecidamente que utilice Microsoft Graph en lugar de la API de Azure AD Graph para tener acceso a recursos de Azure Active Directory. Nuestros esfuerzos de desarrollo se concentran ahora en Microsoft Graph y no están previstas mejoras adicionales para la API de Azure AD Graph. Hay un número muy limitado de escenarios para los que la API de Azure AD Graph todavía podría ser adecuada; para más información, vea la entrada del blog Microsoft Graph o Azure AD Graph en el centro de desarrollo de Office.
Conceptos de los ámbitos de permiso
Comparación entre ámbitos solo de aplicación y ámbitos delegados
Los ámbitos de permiso pueden ser solo de aplicación o delegados. Los ámbitos de solo aplicación, también conocidos como roles de aplicación, otorgan a la aplicación el conjunto completo de privilegios que ofrece el ámbito. Habitualmente, los ámbitos de solo aplicación son usados por las aplicaciones que se ejecutan como servicio sin que esté presente un usuario con sesión iniciada. Los ámbitos de permiso delegados se usan en las aplicaciones en las que inicia sesión un usuario. Estos ámbitos delegan los privilegios del usuario con sesión iniciada a la aplicación, lo que permite que esta actúe como el usuario con sesión iniciada. Los privilegios reales que se otorgan a la aplicación serán la combinación (intersección) privilegiada mínima de los privilegios que el ámbito otorga y que posee el usuario con sesión iniciada. Por ejemplo, si el ámbito de permiso otorga privilegios delegados para escribir todos los objetos de directorio, pero el usuario con sesión iniciada tiene privilegios solo para actualizar su propio perfil de usuario, la aplicación solo podrá escribir el perfil del usuario con sesión iniciada, pero no otros objetos.
Perfiles completos y básicos de usuarios y grupos
El perfil completo (o perfil) de un Usuario o un Grupo incluye todas las propiedades declaradas de la entidad. Como puede que el perfil contenga información confidencial de directorio o información de identificación personal (PII), varios ámbitos restringen el acceso de la aplicación a un conjunto de propiedades limitado, el que se conoce como perfil básico. En el caso de los usuarios, el perfil básico solo incluye las siguientes propiedades: nombre para mostrar, nombre y apellido, foto y dirección de correo electrónico. En el caso de los grupos, el perfil básico solo contiene el nombre para mostrar.
Detalles de los ámbitos de permiso
En la tabla siguiente aparecen los ámbitos de permiso de API Graph y se explica el acceso que otorga cada uno de ellos.
- La columna Ámbito muestra el nombre del ámbito. Los nombres de los ámbitos siguen el formato recurso.operación.restricción; por ejemplo Group.ReadWrite.All. Si la restricción es "All", el ámbito otorga a la aplicación la capacidad de realizar la operación (ReadWrite) en todos los recursos especificados (Group) del directorio; de lo contrario, el ámbito solo permite la operación en el perfil del usuario con sesión iniciada. Los ámbitos pueden otorgar privilegios limitados para la operación especificada; consulte la columna Descripción para ver detalles.
- La columna Permiso muestra cómo se ve el ámbito en el Portal de Azure.
- La columna Descripción describe el conjunto completo de privilegios que el ámbito otorga. En el caso de los ámbitos delegados, el acceso real que se otorga a la aplicación será la combinación (intersección) privilegiada mínima del acceso que el ámbito otorga y los privilegios del usuario con sesión iniciada.
| Ámbito | Permission | Descripción | Tipo de ámbito | Requiere el consentimiento del administrador |
|---|---|---|---|---|
| User.Read | Habilitar el inicio de sesión y leer el perfil del usuario | Permite que los usuarios inicien sesión en la aplicación y que la aplicación lea el perfil completo del usuario con sesión iniciada. El perfil completo incluye todas las propiedades declaradas de la entidad de usuario. User.Read permite que la aplicación lea la siguiente información básica de la empresa del usuario con sesión iniciada (mediante el objeto TenantDetail): id. de inquilino, nombre para mostrar de inquilino y dominios comprobados. La aplicación no puede leer las propiedades de navegación, como el administrador o los subordinados directos. La aplicación no puede leer la contraseña del usuario. | delegado | No |
| User.ReadBasic.All | Leer los perfiles básicos de todos los usuarios | Permite que la aplicación lea el perfil básico de todos los usuarios de la organización en nombre del usuario con sesión iniciada. Las siguientes propiedades conforman el perfil básico de un usuario: nombre para mostrar, nombre y apellido, foto y dirección de correo electrónico. Para leer los grupos de los que es miembro un usuario, la aplicación también necesitará el ámbito Group.Read.All o Group.ReadWrite.All. | delegado | No |
| User.Read.All | Leer los perfiles completos de todos los usuarios | Similar a User.ReadBasic.All, excepto porque permite que la aplicación lea el perfil completo de todos los usuarios de la organización y cuando se leen las propiedades de navegación, como el administrador y subordinados directos. El perfil completo incluye todas las propiedades declaradas de la entidad de usuario. Para leer los grupos de los que es miembro un usuario, la aplicación también necesitará el ámbito Group.Read.All o Group.ReadWrite.All. La aplicación no puede leer contraseñas de los usuarios. | delegado | Sí |
| Group.Read.All | Leer todos los grupos (versión preliminar) | Permite que la aplicación lea el perfil básico de todos los grupos de la organización en nombre del usuario con sesión iniciada. La aplicación también puede leer el perfil básico de los grupos de los que es miembro un grupo. El perfil básico de un grupo solo incluye el nombre para mostrar del grupo. Para leer la información de perfil de los miembros de un grupo, la aplicación también necesitará el ámbito User.ReadBasic o User.Read.All. | delegado | Sí |
| Group.ReadWrite.All | Leer y escribir todos los grupos (versión preliminar) | Permite que la aplicación lea el perfil completo de todos los grupos de la organización, además de crear y actualizar grupos en nombre del usuario con sesión iniciada. La aplicación también puede leer el perfil completo de los grupos de los que es miembro un grupo. El perfil completo incluye todas las propiedades declaradas de la entidad de grupo. Para leer los perfiles de los miembros de un grupo o actualizarlos, la aplicación también necesitará el ámbito User.ReadBasic o User.Read.All. | delegado | Sí |
| Device.ReadWrite.All | Leer y escribir todos los dispositivos | Permite que la aplicación lea y escriba todas las propiedades de dispositivo sin un usuario con sesión iniciada. No permite la creación o eliminación de dispositivos ni actualizar los identificadores alternativos de seguridad de dispositivo. | solo de aplicación | Sí |
| Directory.Read.All | Leer datos de directorio | Permite que la aplicación lea todos los datos del directorio de la organización, como usuarios, grupos y aplicaciones, y las propiedades de navegación asociadas. Nota: Los usuarios pueden consentir las aplicaciones que requieren este permiso si la aplicación está registrada en el inquilino de su propia organización. | solo de aplicación, delegado | Sí |
| Directory.ReadWrite.All | Leer y escribir datos de directorio | Permite que la aplicación lea todos los datos del directorio de la organización. Permite que la aplicación cree y actualice usuarios y grupos y, además, actualicen las propiedades de navegación; sin embargo, prohíbe la eliminación de usuarios o grupos. También permite que la aplicación defina extensiones de esquema en las aplicaciones. Para obtener una lista detallada de privilegios, consulte el detalle de los privilegios de Directory.ReadWrite.All a continuación. | solo de aplicación, delegado | Sí |
| Directory.AccessAsUser.All | Obtener acceso al directorio como el usuario con sesión iniciada | Permite que la aplicación tenga el mismo acceso a los datos del directorio de la organización que tiene el usuario con sesión iniciada. Nota: Una aplicación cliente nativa puede tener el consentimiento del usuario para este permiso; sin embargo, una aplicación web requiere el consentimiento del administrador. | delegado | Sí |
Nota: De manera predeterminada, cuando se crea una aplicación mediante el Portal de Azure, Azure AD le asigna un ámbito de permiso delegado de User.Read.
Detalle de los privilegios de Directory.ReadWrite.All
El ámbito de permisos Directory.ReadWrite.All otorga los siguientes privilegios:
- Lectura completa de todos los objetos del directorio (tanto las propiedades declaradas como las propiedades de navegación)
- Crear y actualizar usuarios
- Deshabilitar y habilitar usuarios (pero no el administrador de la compañía)
- Definir el id. de seguridad alternativo del usuario (pero no los administradores)
- Crear y actualizar grupos
- Administrar pertenencias a grupos
- Actualizar al propietario del grupo
- Administrar asignaciones de licencia
- Definir las extensiones de esquema en las aplicaciones
- Permite establecer la contraseña al crear un usuario.
- Nota: No se otorgan derechos para restablecer las contraseñas de usuario.
- Nota: No se otorgan derechos para leer las contraseñas de usuario.
- Nota: No se otorgan derechos para eliminar entidades (incluidos usuarios o grupos).
- Nota: Se excluye específicamente la creación o actualización de entidades que no se mencionan anteriormente. Estas incluyen: Application, Oauth2PermissionGrant, AppRoleAssignment, Device, ServicePrincipal, TenantDetail, dominios, etc.
Escenarios de los ámbitos de permiso
En la tabla siguiente se muestran los ámbitos de permiso que se necesitan para que una aplicación pueda realizar operaciones específicas. Tenga en cuenta que, en algunos casos, la capacidad que tiene la aplicación para realizar algunas operaciones dependerá de si el ámbito de permiso es delegado o solo de aplicación y, en caso de los ámbitos de permiso delegados, de los privilegios del usuario con sesión iniciada.
| Escenario | Acceso requerido | Ámbito de permiso necesario |
|---|---|---|
| Iniciar sesión y mostrar un icono con el nombre y una foto en miniatura del usuario. | Leer el perfil completo del usuario con sesión iniciada. Leer la información básica de la compañía. |
User.Read |
| Selector básico de personas. | Leer el perfil básico de todos los usuarios en nombre del usuario con sesión iniciada. | User.ReadBasic.All |
| Selector de personas con perfil completo. | Similar al anterior, pero se obtiene acceso al perfil completo de los usuarios en nombre del usuario con sesión iniciada. | User.Read.All |
| Navegador de organigrama. | Leer el perfil completo de todos los usuarios, sus administradores y subordinados directos en nombre del usuario con sesión iniciada. | User.Read.All |
| Selector de personas que incluye grupos para el control de acceso a la aplicación. Visor de grupos y pertenencias. |
Leer el perfil básico de todos los grupos y usuarios en nombre del usuario con sesión iniciada. Leer los perfiles de usuario básicos del administrador y los subordinados directos de los usuarios. Leer el perfil básico de las pertenencias a grupos de los usuarios. Leer el perfil básico de las pertenencias a grupos de los grupos. Leer el perfil básico de los miembros de los grupos. |
User.ReadBasic.All y Group.Read.All |
| Mostrar el perfil del usuario con sesión iniciada y el administrador, los subordinados directos y las pertenencias a grupos del usuario. | Usar las operaciones me para leer lo siguiente: El perfil completo del usuario con sesión iniciada. El perfil completo del administrador y los subordinados directos del usuario con sesión iniciada. El perfil básico de los grupos de los que es miembro el usuario con sesión iniciada. Nota: La combinación de los dos ámbitos otorga más acceso que los que se indican aquí para las operaciones me. |
User.Read.All y Group.Read.All |
| Servicio de administración de grupos que permite que los usuarios creen y administren grupos. | Leer el perfil completo de todos los grupos y usuarios en nombre del usuario con sesión iniciada. Leer los perfiles completos del administrador y los subordinados directos de los usuarios. Leer el perfil completo de las pertenencias a grupos de los usuarios. Lea el perfil completo de las pertenencias a grupos de los grupos. Lea el perfil completo de los miembros de los grupos. Cree y actualice los grupos y sus propiedades de navegación (miembros). |
User.Read.All y Group.ReadWrite.All |
| Lea todos los objetos de directorio (incluidas las propiedades de navegación). | Directory.Read.All | |
| Lea todos los objetos de directorio (incluidas las propiedades de navegación). Cree y actualice objetos de usuario y de grupo. No se permite la eliminación de usuarios o grupos. Nota: Aquí no aparecen todos los privilegios otorgados. |
Directory.ReadWrite.All | |
| Actúe como el usuario con sesión iniciada. | Lea y escriba objetos de directorio (incluidas las propiedades de navegación) en nombre del usuario con sesión iniciada. | Directory.AccessAsUser.All |
Acceso predeterminado para administradores, usuarios y usuarios invitados
En la tabla siguiente se ilustra el acceso predeterminado de administradores (globales), usuarios y usuarios invitados en el directorio. El acceso predeterminado puede aumentar o disminuir más según los ajustes de configuración del directorio o la pertenencia de un usuario en uno o más roles de directorio. Para más información sobre cómo configurar el acceso de los usuarios y los usuarios invitados a los datos de directorio, consulte Adición o cambio de usuarios en Azure Active Directory. Para más información sobre el acceso asociado con varios roles de directorio, consulte Asignación de roles de administrador en Azure Active Directory (Azure AD).
| Tipo de usuario | Acceso |
|---|---|
| Administrador global | Leer todos los objetos de directorio. Crear, actualizar y eliminar todos los objetos de directorio |
| User | Leer todos los objetos de directorio. Crear aplicaciones y entidades de servicio asociadas. Actualizar el perfil. Actualizar los grupos que poseen (y la propiedad de miembros). Actualizar las aplicaciones y entidades de servicio que poseen. Eliminar las aplicaciones y entidades de servicio que poseen. |
| Usuario invitado | Leer el perfil completo. Leer los perfiles básicos de todos los otros usuarios. Leer el perfil básico de todos los grupos. Leer las aplicaciones. Actualizar algunas propiedades del perfil. Sin búsqueda de usuario o grupo (consulte Limitaciones de búsqueda de usuario o grupo para usuarios invitados a continuación). |
Limitaciones de búsqueda de usuario o grupo para usuarios invitados
Las funcionalidades de búsqueda de usuario y grupo permiten que la aplicación busque a cualquier usuario o grupo en el directorio de cliente mediante la ejecución de consultas en el conjunto de recursos users o groups (por ejemplo, https://graph.windows.net/myorganization/users?api-version=1.6). Tanto administradores como usuarios tienen esta funcionalidad. Los usuarios invitados no. Si el usuario con sesión iniciada es un usuario invitado, y en función del ámbito de permiso, una aplicación puede leer el perfil de un usuario o grupo específico mediante el id. de objeto o un nombre principal de usuario (UPN) de un usuario o el id. de objeto de un grupo (por ejemplo https://graph.windows.net/myorganization/users/241f22af-f634-44c0-9a15-c8cd2cea5531?api-version=1.6); sin embargo, no puede realizar consultas en el conjunto de recursos de users o groups que posiblemente solicite más de una entidad. Por ejemplo, y en función del ámbito de permiso, la aplicación puede leer los perfiles de usuarios o grupos que obtiene si sigue los vínculos en las propiedades de navegación, pero no puede emitir una consulta que devuelva a todos los usuarios o grupos del directorio.