Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Importante
Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.
Microsoft Graph le permite crear experiencias de aplicaciones basadas en los usuarios y sus relaciones con otros objetos, como grupos, correos electrónicos, calendarios, archivos y roles administrativos. Puede acceder a los datos de usuario y administrarlos mediante operaciones comunes de API, modelos de autorización, privilegios y control de acciones confidenciales.
Acceso a usuarios
El acceso a los usuarios a través de Microsoft Graph tiene dos maneras:
- Por su identificador o userPrincipalName:
/users/{id}o/users/{userPrincipalName} - Mediante el alias
/medel usuario que ha iniciado sesión, que es el mismo que/users/{signed-in user's id}
Operaciones comunes de API
En Microsoft Graph, los usuarios se representan mediante el tipo de recurso de usuario . En la tabla siguiente se enumeran las operaciones comunes que puede realizar con los usuarios.
| Ruta de acceso | Descripción |
|---|---|
/me |
Obtenga los detalles del usuario que ha iniciado sesión. |
/users |
Enumera los usuarios de la organización. |
/users/{id} |
Obtiene un usuario específico por identificador. |
/users/{id}/photo/$value |
Obtiene la foto de perfil del usuario. |
/users/{id}/manager |
Obtiene el administrador del usuario. |
/users/{id}/messages |
Enumera los mensajes de correo electrónico del usuario en su bandeja de entrada principal. |
/users/{id}/events |
Enumera los eventos próximos del usuario en su calendario. |
/users/{id}/drive |
Obtiene el almacén de archivos del OneDrive del usuario. |
/users/{id}/memberOf |
Enumera los grupos de los que el usuario es miembro. |
/users/{id}/joinedTeams |
Enumera los equipos de Microsoft Teams de los que el usuario es miembro. |
POST /invitations |
Invitar a un invitado como parte de la colaboración de empresa a empresa (B2B) en Microsoft Id. externa de Microsoft Entra |
Autorización y privilegios
Microsoft Graph admite permisos delegados y de aplicación para administrar las operaciones de los usuarios. Comprender estos permisos es crucial para un desarrollo de aplicaciones seguro y eficaz.
Algunas operaciones de usuario las puede realizar el usuario que ha iniciado sesión con sus propios datos. Para estas operaciones, el usuario puede conceder a la aplicación Microsoft Graph permisos para acceder a sus propios detalles. Los permisos User.ReadBasic.All, User.Read y User.ReadWrite son dichos permisos.
Otras operaciones, incluida la administración de detalles para otros usuarios, requieren privilegios administrativos concedidos a través de Microsoft Graph permisos que solo los administradores autorizados pueden consentir, así como roles de Microsoft Entra. Además, algunas operaciones se consideran confidenciales y solo los administradores limitados pueden realizarlas. Para obtener más información, consulta las secciones Quién puede restablecer contraseñas y Quién puede actualizar atributos confidenciales .
Permisos de usuario predeterminados en Microsoft Entra ID
Hay dos tipos de usuarios en Microsoft Entra ID: miembros e invitados. Los miembros se crean de forma nativa en el inquilino. Los invitados se unen al espacio empresarial canjeando su invitación y acceden al espacio empresarial como invitados de colaboración de negocio a negocio (B2B).
Los usuarios de Microsoft Entra ID tienen permisos predeterminados que les permiten realizar determinadas operaciones. Este conjunto de permisos predeterminados depende de si el usuario es un usuario miembro o invitado, y el administrador de inquilinos puede cambiar la configuración de estos permisos predeterminados. Para obtener más información sobre lo que pueden hacer los usuarios miembro y los invitados, consulte ¿Cuáles son los permisos de usuario predeterminados en Microsoft Entra ID?.
Permisos de usuario predeterminados en inquilinos externos
También hay permisos predeterminados para los clientes de Microsoft Entra ID en inquilinos externos. En la tabla siguiente se muestran las operaciones de API que los clientes pueden usar para administrar su propio perfil.
El id. de usuario o userPrincipalName es siempre el del usuario que ha iniciado sesión.
| Operación de usuario | Operación de API | Permisos necesarios |
|---|---|---|
| Leer perfil |
GET /me o GET /users/{id or userPrincipalName} |
User.Read |
| Actualizar perfil |
PATCH /me o PATCH /users/{id or userPrincipalName} Las siguientes propiedades son actualizables: city, country, displayName, givenName, jobTitle, postalCode, state, streetAddress, surname y preferredLanguage |
User.ReadWrite |
| Cambiar contraseña | POST /me/changePassword |
Directory.AccessAsUser.All |
Propiedades de perfil básicas de usuario
El permiso User.ReadBasic.All restringe el acceso de la aplicación a la lectura de un conjunto limitado de propiedades para las cuentas profesionales o educativas de otros usuarios. Este perfil básico incluye solo las siguientes propiedades:
- displayName
- givenName
- id
- photo
- securityIdentifier
- surname
- userPrincipalName
Además, los siguientes permisos específicos del escenario también permiten que las aplicaciones lean el perfil de usuario básico que contiene principalmente propiedades relacionadas con el identificador:
- User-Mail.ReadWrite.All
- User-PasswordProfile.ReadWrite.All
- User-Phone.ReadWrite.All
- User-LifeCycleInfo.Read.All
- User-LifeCycleInfo.ReadWrite.All
Acciones confidenciales
Las siguientes acciones en el objeto de usuario se consideran confidenciales y podrían bloquearse solo para administradores específicos. Todos los usuarios pueden leer las propiedades confidenciales.
| Acción confidencial | Nombre de propiedad confidencial |
|---|---|
| Deshabilitar o habilitar usuarios | accountEnabled |
| Actualizar el teléfono del trabajo | businessPhones |
| Actualizar teléfono móvil | mobilePhone |
| Actualizar el identificador inmutable local | onPremisesImmutableId |
| Actualizar otros correos electrónicos | otherMails |
| Actualizar perfil de contraseña | passwordProfile |
| Actualizar el nombre principal del usuario | userPrincipalName |
| Suprimir o restaurar usuarios | No aplicable |
Quién puede realizar acciones confidenciales
En la tabla siguiente, las columnas enumeran los roles que pueden realizar acciones confidenciales. Las filas enumeran los roles para los que se puede realizar la acción confidencial.
La tabla siguiente es para los roles asignados en el ámbito de un espacio empresarial. Para los roles asignados en el ámbito de una unidad administrativa, se aplican restricciones adicionales.
| Rol en el que se puede realizar una acción confidencial | Administración de Administración | Usuario de Administración | Administración de autenticación con privilegios de Administración | Administrador global |
|---|---|---|---|---|
| Administración de Administración | ✅ | ✅ | ✅ | |
| Lectores de directorios | ✅ | ✅ | ✅ | ✅ |
| Administrador global | ✅ | ✅ | ||
| Grupo de Administración | ✅ | ✅ | ✅ | |
| Invitador de usuarios invitados | ✅ | ✅ | ✅ | ✅ |
| Administración del departamento de soporte técnico | ✅ | ✅ | ✅ | |
| Lector del centro de mensajes | ✅ | ✅ | ✅ | ✅ |
| Contraseña de Administración | ✅ | ✅ | ✅ | ✅ |
| Administración de autenticación con privilegios de Administración | ✅ | ✅ | ||
| Roles de Administración con privilegios | ✅ | ✅ | ||
| Lector de informes | ✅ | ✅ | ✅ | ✅ |
| Usuario (sin rol de administrador) |
✅ | ✅ | ✅ | ✅ |
| Usuario (sin rol de administrador, pero miembro o propietario de un grupo asignable a un rol) |
✅ | ✅ | ||
| Usuario con un rol asignado a una unidad administrativa de administración restringida | ✅ | ✅ | ||
| Usuario de Administración | ✅ | ✅ | ✅ | |
| Resumen de uso de Lector de informes | ✅ | ✅ | ✅ | ✅ |
| Todos los roles personalizados | ✅ | ✅ |
¿Quién puede restablecer contraseñas?
En la tabla siguiente, las columnas enumeran los roles que pueden restablecer contraseñas e invalidar tokens de actualización. En las filas se enumeran los roles para los que se puede restablecer la contraseña del usuario. Por ejemplo, un administrador de contraseñas puede restablecer la contraseña para los lectores de directorios, el invitador de invitados, el administrador de contraseñas y los usuarios sin rol de administrador. Si a un usuario se le asigna cualquier otro rol, el administrador de contraseñas no puede restablecer su contraseña.
La tabla siguiente es para los roles asignados en el ámbito de un espacio empresarial. Para los roles asignados en el ámbito de una unidad administrativa, se aplican restricciones adicionales.
| Rol que se puede restablecer la contraseña | Contraseña de Administración | Administración del departamento de soporte técnico | Administración de Administración | Usuario de Administración | Administración de autenticación con privilegios de Administración | Administrador global |
|---|---|---|---|---|---|---|
| Administración de Administración | ✅ | ✅ | ✅ | |||
| Lectores de directorios | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Administrador global | ✅ | ✅* | ||||
| Grupo de Administración | ✅ | ✅ | ✅ | |||
| Invitador de usuarios invitados | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Administración del departamento de soporte técnico | ✅ | ✅ | ✅ | ✅ | ||
| Lector del centro de mensajes | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Contraseña de Administración | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Administración de autenticación con privilegios de Administración | ✅ | ✅ | ||||
| Roles de Administración con privilegios | ✅ | ✅ | ||||
| Lector de informes | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Usuario (sin rol de administrador) |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Usuario (sin rol de administrador, pero miembro o propietario de un grupo asignable a un rol) |
✅ | ✅ | ||||
| Usuario con un rol asignado a una unidad administrativa de administración restringida | ✅ | ✅ | ||||
| Usuario de Administración | ✅ | ✅ | ✅ | |||
| Resumen de uso de Lector de informes | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Todos los roles personalizados | ✅ | ✅ |
La capacidad de restablecer una contraseña incluye la actualización de las siguientes propiedades confidenciales necesarias para el autoservicio de restablecimiento de contraseña:
- businessPhones
- mobilePhone
- otherMails
Propiedades comunes
✅ Se aplica solo a la versión 1.0.
A continuación se representa el conjunto predeterminado de propiedades que se devuelven al obtener un usuario o enumerar usuarios en v1.0. Estos son un subconjunto de todas las propiedades disponibles en v1.0. Para obtener más propiedades de usuario, use el parámetro de consulta $select. Obtenga información sobre cómo usar el parámetro $consulta de selección y vea propiedades que admiten el parámetro $consulta de selección.
Para obtener detalles y una lista de todas las propiedades, consulte el objeto de usuario .
| Propiedad | Descripción |
|---|---|
| id | El identificador único del usuario. |
| businessPhones | Los números de teléfono del usuario. |
| displayName | El nombre del usuario que aparece en la libreta de direcciones. |
| givenName | El nombre de pila del usuario. |
| jobTitle | El puesto del usuario. |
| La dirección de correo del usuario. | |
| mobilePhone | El número de teléfono móvil del usuario. |
| officeLocation | La ubicación de la oficina física del usuario. |
| preferredLanguage | El idioma de preferencia del usuario. |
| surname | El apellido del usuario. |
| userPrincipalName | El nombre principal del usuario. |
Para obtener información detallada y una lista de todas las propiedades, consulte el objeto user.
Limitaciones de búsqueda de usuarios y grupos para invitados
Las funciones de búsqueda de grupos y usuarios permiten que la aplicación busque cualquier usuario o grupo en un directorio de la organización mediante la realización de consultas en el conjunto de recursos /users o /groups (por ejemplo, https://graph.microsoft.com/v1.0/users). Tanto los administradores como los usuarios que son miembros tienen esta capacidad; Sin embargo, los usuarios invitados no lo hacen.
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 usuario o grupo específico (por ejemplo, https://graph.microsoft.com/v1.0/users/241f22af-f634-44c0-9a15-c8cd2cea5531), pero no puede realizar consultas en el conjunto de recursos /users o /groups que devuelvan potencialmente más de un solo recurso.
Con los permisos adecuados, la aplicación puede leer los perfiles de usuarios o grupos que obtiene al seguir los vínculos de las propiedades de navegación, como /users/{id}/directReports o /groups/{id}/members.
Propiedades no devueltas de manera predeterminada
Algunas propiedades del objeto de usuario no se devuelven de forma predeterminada y deben especificarse en un $select parámetro de consulta. Por ejemplo, cumpleaños y habilidades. Consulte la tabla de propiedades de la entidad de usuario para identificar las propiedades que solo se devuelven cuando .$select
Propiedades almacenadas fuera del almacén de datos principal
Aunque los datos de recursos de usuario se almacenan principalmente en Microsoft Entra ID, algunas de sus propiedades, como las aptitudes, se almacenan en SharePoint Online. En la mayoría de los casos, no puedes especificar estas propiedades en el mismo cuerpo de la solicitud de Creación o Actualización que otras propiedades de usuario.
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 como resultado que un objeto aparezca en la respuesta de la consulta delta.
Las siguientes propiedades del objeto de usuario se almacenan fuera del almacén de datos principal: signInActivity, cloudLicensing, mailboxSettings, deviceEnrollmentLimit, print, aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills.
Conclusión
Microsoft Graph proporciona potentes funcionalidades para administrar los datos de usuario e interactuar con ellos. Si comprende los diferentes permisos, las operaciones comunes de API y el control de las acciones confidenciales, puede crear aplicaciones seguras y eficientes. Para obtener más información, consulte los vínculos de contenido y documentación relacionados.