Основные сведения о проверке подлинности и авторизации для Microsoft Graph

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

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

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

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

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

EwAoA8l6BAAU7p9QDpi/D7xJLwsTgCg3TskyTaQAAXu71AU9f4aS4rOK5xoO/SU5HZKSXtCsDe0Pj7uSc5Ug008qTI+a9M1tBeKoTs7tHzhJNSKgk7pm5e8d3oGWXX5shyOG3cKSqgfwuNDnmmPDNDivwmi9kmKqWIC9OQRf8InpYXH7NdUYNwN+jljffvNTewdZz42VPrvqoMH7hSxiG7A1h8leOv4F3Ek/oeJX6U8nnL9nJ5pHLVuPWD0aNnTPTJD8Y4oQTp5zLhDIIfaJCaGcQperULVF7K6yX8MhHxIBwek418rKIp11om0SWBXOYSGOM0rNNN59qNiKwLNK+MPUf7ObcRBN5I5vg8jB7IMoz66jrNmT2uiWCyI8MmYDZgAACPoaZ9REyqke+AE1/x1ZX0w7OamUexKF8YGZiw+cDpT/BP1GsONnwI4a8M7HsBtDgZPRd6/Hfqlq3HE2xLuhYX8bAc1MUr0gP9KuH6HDQNlIV4KaRZWxyRo1wmKHOF5G5wTHrtxg8tnXylMc1PKOtaXIU4JJZ1l4x/7FwhPmg9M86PBPWr5zwUj2CVXC7wWlL/6M89Mlh8yXESMO3AIuAmEMKjqauPrgi9hAdI2oqnLZWCRL9gcHBida1y0DTXQhcwMv1ORrk65VFHtVgYAegrxu3NDoJiDyVaPZxDwTYRGjPII3va8GALAMVy5xou2ikzRvJjW7Gm3XoaqJCTCExN4m5i/Dqc81Gr4uT7OaeypYTUjnwCh7aMhsOTDJehefzjXhlkn//2eik+NivKx/BTJBEdT6MR97Wh/ns/VcK7QTmbjwbU2cwLngT7Ylq+uzhx54R9JMaSLhnw+/nIrcVkG77Hi3neShKeZmnl5DC9PuwIbtNvVge3Q+V0ws2zsL3z7ndz4tTMYFdvR/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==

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

Чтобы получить маркер из платформы удостоверений Майкрософт, приложение должно быть зарегистрировано на портале 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, с другой стороны.

  • В случае делегированных разрешений действующие разрешения приложения — это разрешения, одновременно являющиеся делегированными приложению (путем оформления согласия) разрешениями и привилегиями вошедшего пользователя. У вашего приложения никогда не может быть больше привилегий, чем у вошедшего пользователя. В организациях привилегии вошедшего пользователя определяются политикой или членством в одной или нескольких ролях администратора. Дополнительные сведения о ролях администратора см. в статье Назначение ролей администратора в Azure Active Directory.

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

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

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

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

Администраторы могут настроить политику доступа приложения, чтобы ограничить его доступ определенными почтовыми ящиками.

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также