Общие сведения о разрешениях и согласии в Microsoft Graph

  • 6 мин

Для разработки клиентского приложения, которое извлекает данные Microsoft 365, необходимо понимать, как работают разрешения и согласие в Microsoft Graph. Нужно правильно выбрать, к каким данным ваше приложение может получать доступ, а к каким нет. Например, если вы хотите показать предстоящие собрания для выполнившего вход продавца, нужно, чтобы у вашего приложения было разрешение на доступ к данным календаря этого пользователя из Microsoft 365.

Приложения запрашивают разрешение на доступ к определенным ресурсам Microsoft 365 через Microsoft Graph. Эти запросы могут делаться заранее (при регистрации приложения) или динамически (когда приложение запущено). Когда приложение запрашивает разрешение, пользователь или администратор должен согласиться на предоставление разрешения, прежде чем Microsoft Graph авторизует запросы.

Когда вашему приложению необходимо взаимодействовать с Microsoft Graph, вам необходимо разобраться в трех следующих основных понятиях.

  • Разрешения или области Microsoft Graph
  • Типы разрешений
  • Маркеры доступа

Разрешения или области Microsoft Graph

Разрешения Microsoft Graph содержат области, контролирующие доступ приложения к определенным ресурсам, таким как пользователи, почта и файлы. Области также контролируют операции, которые могут быть выполнены с этими ресурсами. В следующем примере шаблона определяется разрешение на операцию Microsoft Graph для некоторого ресурса:

Resource-name.operation.constraint

Например, User.Read.All предоставляет приложению разрешение на чтение профилей всех пользователей в каталоге. Чтобы прочитать профиль выполнившего вход пользователя, необходимо разрешение User.Read.

Типы разрешений

Существует два типа разрешений в идентификаторе Microsoft Entra:

  • Ваше приложение использует делегированное разрешение, когда оно вызывает Microsoft Graph от имени пользователя. Пользователь может дать согласие на использование некоторых областей разрешений, таких как User.Read. Однако некоторые области разрешений имеют высокие привилегии и требуют согласия администратора. Примером области разрешений с высокими привилегиями является Channel.Delete.All для удаления каналов в любой команде от имени выполнившего вход пользователя.

    Простейший пример области делегированного разрешения — область User.Read, необходимая для вызова конечной точки /me. В Microsoft Graph все вызовы API с /me используют контекст выполнившего вход пользователя.

  • Разрешение приложения не требует входа пользователя в приложение. Оно часто используется в отсутствие пользователя, например в фоновом процессе или для повышения уровня разрешения. Администратор дает согласие на предоставление разрешения заранее.

    Примером области разрешения приложения является область Calendars.ReadWrite, которая позволяет приложению создавать, читать, обновлять и удалять события всех календарей без выполнившего вход пользователя. Вы не можете использовать API /me для области разрешения приложения, так как отсутствует выполнивший вход пользователь для извлечения этой информации.

Маркеры доступа

После запроса разрешения приложением и согласия пользователя или администратора приложение может получить маркер доступа от платформы удостоверений Майкрософт. Можно представить маркер доступа как билет в кино, который вы предъявляете контролеру в подтверждение оплаты просмотра фильма. Приложение предъявляет Microsoft Graph маркер доступа, тем самым подтверждая, что у него есть разрешение на доступ к данным Microsoft 365.

Microsoft Graph требует наличия действительного маркера доступа в заголовке каждого запроса. Он передается в заголовке авторизации каждого запроса со словом Bearer и пробелом перед ним. Это напоминание о том, что носитель может использовать маркер доступа подобно билету в кино. То есть любой, у кого есть билет, может войти, не подтверждая свою личность. По этой причине Microsoft Graph требует шифрования HTTPS для всех запросов. Кроме того, как и билеты в кино, маркеры доступа действительны только в течение короткого периода (обычно в один час).

Вот пример заголовка авторизации для запроса Microsoft Graph:

GET https://graph.microsoft.com/v1.0/me/ HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==