Работа с пользователями в Microsoft Graph
Microsoft Graph позволяет создавать привлекательные интерфейсы приложений на основе пользователей и их связей с другими объектами, такими как другие пользователи и группы, членство в группах и ресурсы, к которым они обращаются, например электронные письма, календари, файлы и административные роли.
В этой статье объясняется, как получить доступ к данным пользователей и управлять ими с помощью Microsoft Graph, включая общие операции API, авторизацию, привилегии и обработку конфиденциальных действий.
Доступ к пользователям
Доступ к пользователям через Microsoft Graph осуществляется двумя способами:
- По идентификатору или userPrincipalName,
/users/{id}или/users/{userPrincipalName} - С помощью псевдонима
/me(который совпадает с/users/{signed-in user's id}) для пользователя, вошедшего в систему.
Общие операции API
В Microsoft Graph пользователи представлены типом ресурса пользователя . В следующей таблице перечислены распространенные операции, которые можно выполнять с пользователями.
| Path | Описание |
|---|---|
/me |
Получение сведений о пользователе, выполнившего вход. |
/users |
Вывод списка пользователей в организации. |
/users/{id} |
Возвращает определенного пользователя по идентификатору. |
/users/{id}/photo/$value |
Получение фотографии профиля пользователя. |
/users/{id}/manager |
Получение сведений о руководителе пользователя. |
/users/{id}/messages |
Вывод списка электронных писем пользователя в его основном почтовом ящике. |
/users/{id}/events |
Вывод списка предстоящих событий пользователя из его календаря. |
/users/{id}/drive |
Получение хранилища файлов OneDrive пользователя. |
/users/{id}/memberOf |
Вывод списка групп, участником которых является пользователь. |
/users/{id}/joinedTeams |
Вывод списка команд Microsoft Teams, участником которых является пользователь. |
POST /invitations |
Пригласите гостя в рамках совместной работы "бизнес-бизнес" (B2B) в Внешняя идентификация Microsoft Entra |
Авторизация и привилегии
Microsoft Graph поддерживает делегированные разрешения и разрешения приложений для управления операциями пользователей. Понимание этих разрешений имеет решающее значение для безопасной и эффективной разработки приложений. Дополнительные сведения см. в разделе Делегированные разрешения и разрешения приложений и соответствующую справочную документацию по API для разрешений, необходимых для каждой операции.
Некоторые пользовательские операции могут выполняться вошедшего пользователя с использованием собственных сведений. Для таких операций пользователь может предоставить приложению разрешения Microsoft Graph на доступ к собственным сведениям. Разрешения User.ReadBasic.All, User.Read и User.ReadWrite являются такими разрешениями.
Для других операций, включая управление сведениями для других пользователей, требуются права администратора, предоставляемые с помощью других разрешений Microsoft Graph, на которые могут согласиться и Microsoft Entra роли только полномочные администраторы. Кроме того, некоторые операции считаются конфиденциальными, и их могут выполнять только ограниченные администраторы. Дополнительные сведения см. в разделах Кто может сбрасывать пароли и Кто может обновлять конфиденциальные атрибуты .
Разрешения пользователей по умолчанию в Microsoft Entra ID
В Microsoft Entra ID есть два типа пользователей: участники и гости. Члены создаются в клиенте в собственном коде. Гости присоединяются к клиенту, активируя свое приглашение, и получают доступ к клиенту в качестве гостей совместной работы "бизнес-бизнес" (B2B).
Пользователи в Microsoft Entra ID имеют разрешения по умолчанию, позволяющие им выполнять определенные операции. Этот набор разрешений по умолчанию зависит от того, является ли пользователь участником или гостевым пользователем, и администратор клиента может изменить параметры для этих разрешений по умолчанию. Дополнительные сведения о том, что могут делать пользователи-члены и гостевые пользователи, см. в статье Какие разрешения пользователей по умолчанию в Microsoft Entra ID?.
Разрешения пользователей по умолчанию во внешних клиентах
Существуют также разрешения по умолчанию для клиентов в Microsoft Entra ID во внешних клиентах. В следующей таблице показаны операции API, которые позволяют клиентам управлять собственным профилем.
Идентификатор пользователя или userPrincipalName всегда является именем пользователя, выполнившего вход.
| Операция пользователя | Операция API | Необходимые разрешения |
|---|---|---|
| Профиль чтения |
GET /me или GET /users/{id or userPrincipalName} |
User.Read |
| Обновление профиля |
PATCH /me или PATCH /users/{id or userPrincipalName} Обновляемые свойства: city, country, displayName, givenName, jobTitle, postalCode, state, streetAddress, surname и preferredLanguage |
User.ReadWrite |
| Смена пароля | POST /me/changePassword |
Directory.AccessAsUser.All |
Базовый профиль пользователей
Разрешение User.ReadBasic.All ограничивает доступ приложения к чтению ограниченного набора свойств для рабочих или учебных учетных записей других пользователей. Этот базовый профиль содержит только следующие свойства:
- displayName
- givenName;
- id
- mail;
- photo;
- securityIdentifier
- surname;
- userPrincipalName.
Кроме того, следующие разрешения, относящиеся к сценарию, также позволяют приложениям считывать базовый профиль пользователя, который содержит в основном свойства, связанные с идентификаторами:
- User-Mail.ReadWrite.All
- User-PasswordProfile.ReadWrite.All
- User-Phone.ReadWrite.All
- User-LifeCycleInfo.Read.All
- User-LifeCycleInfo.ReadWrite.All
Конфиденциальные действия
Следующие действия с объектом пользователя считаются конфиденциальными и могут быть заблокированы только определенными администраторами. Все пользователи могут считывать конфиденциальные свойства.
| Конфиденциальное действие | Имя конфиденциального свойства |
|---|---|
| Отключение или включение пользователей | accountEnabled |
| Обновление бизнес-телефона | businessPhones |
| Обновление мобильного телефона | mobilePhone; |
| Обновление локального неизменяемого идентификатора | onPremisesImmutableId |
| Обновление других сообщений электронной почты | otherMails |
| Обновление профиля пароля | passwordProfile |
| Обновление имени участника-пользователя | userPrincipalName. |
| Удаление или восстановление пользователей | Неприменимо |
Кто может выполнять конфиденциальные действия
Некоторые администраторы могут выполнять предыдущие конфиденциальные действия для некоторых пользователей.
В следующей таблице в столбцах перечислены роли, которые могут выполнять конфиденциальные действия. В строках перечислены роли, для которых может выполняться конфиденциальное действие.
В следующей таблице приведены роли, назначенные в область клиента. Для ролей, назначенных на область административной единицы, применяются дополнительные ограничения.
| Роль, с которой может выполняться конфиденциальное действие | Проверка подлинности Администратор | Администратор пользователя | Привилегированная проверка подлинности Администратор | Глобальный администратор |
|---|---|---|---|---|
| Проверка подлинности Администратор | ✅ | ✅ | ✅ | |
| Читатели каталогов | ✅ | ✅ | ✅ | ✅ |
| Глобальный администратор | ✅ | ✅ | ||
| Группы Администратор | ✅ | ✅ | ✅ | |
| Приглашающий гостей | ✅ | ✅ | ✅ | ✅ |
| Администратор службы поддержки | ✅ | ✅ | ✅ | |
| Читатель центра сообщений | ✅ | ✅ | ✅ | ✅ |
| Пароль Администратор | ✅ | ✅ | ✅ | ✅ |
| Привилегированная проверка подлинности Администратор | ✅ | ✅ | ||
| Администратор привилегированных ролей | ✅ | ✅ | ||
| Читатель отчетов | ✅ | ✅ | ✅ | ✅ |
| Пользователь (без роли администратора) |
✅ | ✅ | ✅ | ✅ |
| Пользователь (нет роли администратора, но член или владелец группы с возможностью назначения ролей) |
✅ | ✅ | ||
| Пользователь с ролью, ограниченной административной единицей управления | ✅ | ✅ | ||
| Администратор пользователя | ✅ | ✅ | ✅ | |
| Средство чтения сводки об использовании | ✅ | ✅ | ✅ | ✅ |
| Все настраиваемые роли | ✅ | ✅ |
Кто может сбрасывать пароли
В следующей таблице в столбцах перечислены роли, которые могут сбрасывать пароли и отменять маркеры обновления. В строках перечислены роли, для которых можно сбросить пароль. Например, администратор паролей может сбросить пароль для читателей каталогов, приглашенного гостя, администратора паролей и пользователей без роли администратора. Если пользователю назначена какая-либо другая роль, администратор паролей не может сбросить пароль.
В следующей таблице приведены роли, назначенные в область клиента. Для ролей, назначенных на область административной единицы, применяются дополнительные ограничения.
| Роль, которую можно сбросить пароль | Пароль Администратор | Администратор службы поддержки | Проверка подлинности Администратор | Администратор пользователя | Привилегированная проверка подлинности Администратор | Глобальный администратор |
|---|---|---|---|---|---|---|
| Проверка подлинности Администратор | ✅ | ✅ | ✅ | |||
| Читатели каталогов | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Глобальный администратор | ✅ | ✅* | ||||
| Группы Администратор | ✅ | ✅ | ✅ | |||
| Приглашающий гостей | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Администратор службы поддержки | ✅ | ✅ | ✅ | ✅ | ||
| Читатель центра сообщений | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Пароль Администратор | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Привилегированная проверка подлинности Администратор | ✅ | ✅ | ||||
| Администратор привилегированных ролей | ✅ | ✅ | ||||
| Читатель отчетов | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Пользователь (без роли администратора) |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Пользователь (нет роли администратора, но член или владелец группы с возможностью назначения ролей) |
✅ | ✅ | ||||
| Пользователь с ролью, ограниченной административной единицей управления | ✅ | ✅ | ||||
| Администратор пользователя | ✅ | ✅ | ✅ | |||
| Средство чтения сводки об использовании | ✅ | ✅ | ✅ | ✅ | ✅ | |
| Все настраиваемые роли | ✅ | ✅ |
Возможность сброса пароля включает обновление следующих конфиденциальных свойств, необходимых для самостоятельного сброса пароля:
- businessPhones
- mobilePhone;
- otherMails
Общие свойства
Ниже показан набор свойств, используемый по умолчанию и возвращаемый при получении пользователя или выводе списка пользователей. Это подмножество всех доступных свойств. Чтобы получить дополнительные свойства пользователя, используйте параметр запроса $select. Узнайте, Как использовать параметр поискового запроса $select и каковы Свойства, поддерживающие параметр $select поискового запроса.
Дополнительные сведения и список всех свойств см. в разделе объект user .
| Свойство | Описание |
|---|---|
| id | Уникальный идентификатор для пользователя. |
| businessPhones | Номера телефонов пользователя. |
| displayName | Имя, отображаемое в адресной книге, для пользователя. |
| givenName | Имя пользователя. |
| jobTitle | Должность пользователя. |
| Электронный адрес пользователя. | |
| mobilePhone | Номер мобильного телефона пользователя. |
| officeLocation | Физическое расположение офиса пользователя. |
| preferredLanguage | Предпочитаемый язык пользователя. |
| surname | Фамилия пользователя. |
| userPrincipalName | Имя участника-пользователя для пользователя. |
Дополнительные сведения и список всех свойств см. в статье об объекте user.
Ограничения поиска пользователей и групп для гостей
Функции поиска пользователей и групп позволяют приложению найти любого пользователя и любую группу в каталоге организации с помощью запросов для набора ресурсов /users или /groups (например, https://graph.microsoft.com/v1.0/users). Эту возможность имеют как администраторы, так и пользователи, являющиеся участниками; однако гостевые пользователи этого не сделали.
Если пользователь вошел как гость, в зависимости от предоставленных приложению разрешений оно может прочитать профиль определенного пользователя или определенной группы (например, https://graph.microsoft.com/v1.0/users/241f22af-f634-44c0-9a15-c8cd2cea5531). Но оно не может отправлять набору ресурсов /users или /groups запросы, способные возвращать несколько ресурсов.
При наличии подходящих разрешений приложение может считывать профили пользователей и групп, которые оно получает благодаря ссылкам в свойствах навигации (например, /users/{id}/directReports или /groups/{id}/members).
Свойства, не возвращенные по умолчанию
Некоторые свойства объекта user не возвращаются по умолчанию и должны быть указаны в параметре $select запроса. Например, день рождения и навыки. См. таблицу свойств сущности пользователя , чтобы определить свойства, возвращаемые только в том случае, если вы $select.
Свойства, хранящиеся за пределами хранилища данных main
Хотя данные пользовательского ресурса в основном хранятся в Microsoft Entra ID, некоторые из его свойств, например навыки, хранятся в SharePoint Online. В большинстве случаев эти свойства нельзя указать в том же тексте запроса на создание или обновление, что и другие свойства пользователя.
Свойства, хранящиеся за пределами хранилища данных main, также не поддерживаются в рамках отслеживания изменений. Таким образом, изменение любого из этих свойств не приводит к отображению объекта в ответе разностного запроса.
Следующие свойства объекта пользователя хранятся вне хранилища данных main: signInActivity, cloudLicensing, mailboxSettings, deviceEnrollmentLimit, print, aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, круг обязанностей, учебных заведений, навыков.
Заключение
Microsoft Graph предоставляет мощные возможности для управления данными пользователей и взаимодействия с ними. Понимание различных разрешений, распространенных операций API и обработка конфиденциальных действий позволяют создавать безопасные и эффективные приложения. Дополнительные сведения см. в соответствующем содержимом и ссылках на документацию.