Основы аутентификации и авторизации

Чтобы вызвать Microsoft Graph, ваше приложение должно получить токен доступа от платформы Microsoft Identity. Токен доступа содержит информацию о вашем приложении и разрешениях, которые оно имеет для доступа к ресурсам и API, доступным через Microsoft Graph. Чтобы получить токен доступа, ваше приложение должно быть зарегистрировано на платформе Microsoft Identity и авторизовано пользователем или администратором для доступа к необходимым ресурсам Microsoft Graph.

В этой статье представлен обзор платформы удостоверений Майкрософт, маркеров доступа и того, как ваше приложение может получить маркеры доступа. Дополнительные сведения о платформе удостоверений Майкрософт см. в статье Что такое платформа удостоверений Майкрософт?. Если вы знаете, как интегрировать приложение с платформой удостоверений Майкрософт для получения токенов, ознакомьтесь с информацией и Следующие шаги.

Регистрация приложения с помощью платформы удостоверений Майкрософт

Чтобы получить маркер из платформы удостоверений Майкрософт, приложение должно быть зарегистрировано на портале Azure. При регистрации приложение интегрируется с платформой удостоверений Майкрософт, а также задаются сведения, используемые для получения маркеров, включая:

  • Идентификатор приложения. Уникальный идентификатор, назначенный платформой удостоверений Майкрософт.
  • URI/URL-адрес перенаправления. Одна или несколько конечных точек, в которых приложение будет получать ответы от платформы удостоверений Майкрософт. (Для нативных и мобильных приложений URI назначается платформой удостоверений Майкрософт.)
  • Секрет клиента. Пароль либо пара ключей (открытый и закрытый), используемые приложением для проверки подлинности на платформе удостоверений Майкрософт. (Не требуется для нативных или мобильных приложений.)

Свойства, настроенные во время регистрации, используются в запросе. Например, в приведенном ниже запросе на получение токена client_id — это идентификатор приложения, redirect_uri — один из зарегистрированных для приложения URI перенаправления, а client_secret — секрет клиента.

// Line breaks for legibility only

POST /common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Разрешения Microsoft Graph

Microsoft Graph предоставляет детализированные разрешения, управляющие доступом приложений к ресурсам, таким как пользователи, группы и почта. Вы как разработчик указываете, какие разрешения Microsoft Graph запрашивать для своего приложения. Входя в приложение, пользователь (иногда администратор) получает возможность согласиться с предоставлением этих разрешений. Если пользователь дает согласие, приложение получает доступ к запрашиваемым ресурсам и интерфейсам API. Для приложений, которые получают доступ к ресурсам без вошедшего пользователя, администратор может заранее дать согласие при установке приложения.

Рекомендации по запросу разрешений

Примечание

Рекомендуется запрашивать разрешения с минимальными правами, необходимыми вашему приложению для доступа к данным и правильной работы. Запрос разрешений с правами, превышающими необходимые, отрицательно сказывается на безопасности, и в результате пользователи могут не предоставлять согласие, что повлияет на использование вашего приложения.

Разрешения приложений и делегированные разрешения

В Microsoft Graph есть два типа разрешений:

  • Делегированные разрешения используются приложениями, предусматривающими вход пользователя. Пользователь или администратор предоставляет запрашиваемые разрешения, после чего приложение может вызывать Microsoft Graph от имени вошедшего пользователя. Разрешения высокого уровня может предоставлять только администратор.

  • Разрешения приложений используются приложениями, не требующими входа пользователя (например, фоновыми службами и управляющими программами). Предоставлять эти разрешения может только администратор.

Действующие разрешения

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

Эффективные разрешения в сценариях с делегированными разрешениями и разрешениями только для приложений

  • Для делегированных разрешений действующие разрешения вашего приложения представляют собой наименее привилегированное пересечение делегированных разрешений, предоставленных приложению (по согласию), и привилегий текущего пользователя, вошедшего в систему. Ваше приложение никогда не может иметь больше привилегий, чем вошедший в систему пользователь.

    Предположим, что вашему приложению предоставлено делегированное разрешение User.ReadWrite.All и приложение вызывает API Update user. Обычно это разрешение позволяет приложению считывать и обновлять профиль любого пользователя в организации. Однако из-за действующих разрешений к правам вошедшего пользователя применяются следующие ограничения.

    • Если вошедший пользователь является глобальным администратором, приложение может обновлять профиль любого пользователя в организации.
    • Если вошедший пользователь не является администратором, то приложение может обновлять только профиль вошедшего пользователя. Оно не сможет обновлять профили других пользователей в организации, поскольку вошедший пользователь не обладает этими привилегиями.
  • В случае разрешений приложения действующими разрешениями приложения являются полные привилегии, предусмотренные разрешением. Например, приложение с разрешением User.ReadWrite.All приложения может обновлять профиль любого пользователя в организации.

Сравнение делегированных разрешений и разрешений приложения

Item Делегированные разрешения Разрешения приложений
Сценарии типов приложений Веб-приложение, мобильное приложение или одностраничное приложение (SPA) Веб-приложение / управляющая программа
Контекст доступа Получение доступа от имени пользователя Получение доступа в качестве службы
Кто может дать согласие
  • Пользователи могут дать согласие, связанное с их данными
  • Администраторы могут дать согласие для всех пользователей
  • Дать согласие может только администратор
    Другие имена
  • scopes
  • Разрешения OAuth2
  • Роли приложений
  • Разрешения только для приложения
  • Разрешения на прямой доступ
  • Результат согласия oAuth2PermissionGrants appRoleAssignments

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

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

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

    Маркеры доступа, выпущенные платформой удостоверений Майкрософт, содержат сведения (утверждения), с помощью которых веб-API, защищенные платформой удостоверений Майкрософт, такой как Microsoft Graph, проверяют вызывающую сторону и гарантируют наличие у нее необходимых разрешений на выполнение запрашиваемой операции. Вызывавшему следует рассматривать маркеры доступа как непрозрачные строки, так как содержимое маркера предназначено только для API. При вызове Microsoft Graph всегда защищайте маркеры доступа, передавая их по безопасному каналу, который использует протокол TLS.

    Ниже приведен пример маркера доступа платформы удостоверений Майкрософт:

    EwAoA8l6BAAU7p9QDpi/D7xJLwsTgCg3TskyTaQAAXu71AU9f4aS4rOK5xoO/SU5HZKSXtCsDe0Pj7uSc5Ug008qTI+a9M1tBeKoTs7tHzhJNSKgk7pm5e8d3oGWXX5shyOG3cKSqgfwuNDnmmPDNDivwmi9kmKqWIC9OQRf8InpYXH7NdUYNwN+jljffvNTewdZz42VPrvqoMH7hSxiG7A1h8leOv4F3Ek/XbrnbEErTDLWrV6Lc3JHQMs0bYUyTBg5dThwCiuZ1evaT6BlMMLuSCVxdBGzXTBcvGwihFzZbyNoX+52DS5x+RbIEvd6KWOpQ6Ni+1GAawHDdNUiQTQFXRxLSHfc9fh7hE4qcD7PqHGsykYj7A0XqHCjbKKgWSkcAg==
    

    Чтобы вызвать Microsoft Graph, необходимо вложить маркер доступа (в качестве токена носителя) в заголовок Authorization HTTP-запроса. Например, следующий вызов возвращает данные профиля вошедшего пользователя (для удобства маркер доступа сокращен).

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

    Токены доступа — это своего рода токены безопасности, предоставляемые платформой удостоверений Майкрософт. Они недолговечны, но с переменным временем жизни по умолчанию. Дополнительные сведения о токенах доступа и о том, как клиенты используют токены доступа, см. в разделе Токены доступа.

    Получение токена доступа

    Как и большинство разработчиков, вы, вероятно, будете использовать библиотеки проверки подлинности для управления взаимодействием маркера с платформой удостоверений Майкрософт. Библиотеки проверки подлинности позволяют разработчику отвлечься от многих подробностей протокола (например, проверки, обработки файлов cookie, кэширования маркеров и поддержки защищенных соединений) и сосредоточить внимание на разработке функций приложения. Корпорация Майкрософт публикует клиентские библиотеки с открытым кодом и серверное ПО промежуточного слоя.

    Для конечной точки платформы удостоверений Майкрософт:

    • Клиентские библиотеки MSAL — библиотеки проверки подлинности (Майкрософт) — доступны для платформ .NET, JavaScript, Android и Objective-C. Все платформы находятся в стадии разработки с поддержкой для рабочих сред, а в случае внесения критических изменений корпорация Майкрософт гарантирует возможность обновления.
    • Серверное ПО промежуточного слоя от корпорации Майкрософт доступно для .Net Core и ASP.NET (OWIN OpenID Connect и OAuth), а также для Node.js (Passport.js платформы удостоверений Майкрософт).
    • Платформа удостоверений Майкрософт совместима со множеством сторонних библиотек проверки подлинности.

    Полный список клиентских библиотек и серверного ПО промежуточного слоя от корпорации Майкрософт, а также совместимых сторонних библиотек см. в статье Библиотеки проверки подлинности платформы удостоверений Майкрософт.

    Для получения маркера доступа не нужно использовать библиотеку проверки подлинности. Сведения о непосредственном использовании конечных точек платформы удостоверений Майкрософт без помощи библиотеки проверки подлинности см. в статье Проверка подлинности платформы удостоверений Майкрософт

    Дальнейшие действия

    Если вы готовы перейти к коду, можете воспользоваться указанными ниже ресурсами, которые помогут вам реализовать проверку подлинности и авторизацию с помощью платформы удостоверений Майкрософт в приложении.

    Обучение и примеры по Microsoft Graph

    Чтобы помочь вам быстро начать работу, мы создали серию учебных модулей и других ресурсов, которые показывают, как выполнять проверку подлинности и использовать API на различных платформах.

    Примеры и документация по платформе удостоверений Майкрософт

    Документация по платформе удостоверений Майкрософт содержит статьи и примеры, в которых внимание уделяется проверке подлинности и авторизации с помощью платформы удостоверений Майкрософт.

    См. также