Области и разрешения в платформа удостоверений Майкрософт

  • Статья

Платформа удостоверений Майкрософт реализует протокол авторизации OAuth 2.0. OAuth 2.0 — это метод, посредством которого стороннее приложение может обращаться к интернет-ресурсам от имени пользователя. Любой интернет-ресурс, интегрируемый с платформой удостоверений Майкрософт, имеет идентификатор ресурса или универсальный код ресурса (URI) идентификатора приложения.

В этой статье вы узнаете о областях и разрешениях на платформе удостоверений.

В следующем списке показаны некоторые примеры ресурсов, размещенных в Интернете Майкрософт:

  • Microsoft Graph: https://graph.microsoft.com
  • API почты Microsoft 365: https://outlook.office.com
  • Azure Key Vault: https://vault.azure.net

То же касается любых сторонних ресурсов, интегрированных с платформой удостоверений Майкрософт. Любой из этих ресурсов также может определить набор разрешений, которые можно использовать для разделения функциональности этого ресурса на небольшие блоки. Например, в Microsoft Graph определены разрешения для выполнения таких задач, как:

  • чтение календаря пользователя;
  • запись в календарь пользователя;
  • отправка сообщений в качестве пользователя.

Благодаря определениям разрешений этих типов ресурс получает детализированный контроль над своими данными и предоставлением внешнего доступа к функционалу API. Стороннее приложение может запрашивать эти разрешения у пользователей и администраторов. Они должны подтвердить такой запрос, прежде чем приложение получит доступ к данным или начнет действовать от имени пользователя.

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

В OAuth 2.0 наборы разрешений такого типа называются областями. Также их часто называют просто разрешениями. На платформе удостоверений Майкрософт они представлены в виде строковых значений. Приложение запрашивает необходимые разрешения, указывая разрешение в параметре запроса scope. Платформа удостоверений поддерживает несколько четко определенных областей OpenID Connect и разрешений на основе ресурсов (каждое разрешение указывается путем добавления значения разрешения к идентификатору ресурса или URI идентификатора приложения). Например, строка разрешений https://graph.microsoft.com/Calendars.Read используется для запроса разрешения на чтение календарей пользователей в Microsoft Graph.

В запросах к серверу авторизации для платформа удостоверений Майкрософт, если идентификатор ресурса опущен в параметре области, ресурс считается Microsoft Graph. Например, выражение scope=User.Read будет эквивалентно https://graph.microsoft.com/User.Read.

Разрешения, предназначенные только для администраторов

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

  • User.Read.All: чтение всех профилей пользователей
  • Directory.ReadWrite.All: запись данных в каталог организации
  • Groups.Read.All: чтение всех групп в каталоге организации

Примечание.

В запросах к конечным точкам авторизации, маркера или согласия для платформа удостоверений Майкрософт, если идентификатор ресурса опущен в параметре области, ресурс считается Microsoft Graph. Например, выражение scope=User.Read будет эквивалентно https://graph.microsoft.com/User.Read.

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

Если приложение запрашивает разрешения приложения, а администратор предоставляет эти разрешения, это разрешение не выполняется от имени какого-либо конкретного пользователя. а напрямую клиентскому приложению. Эти типы разрешений должны использоваться только службами управляющей программы и другими неинтерактивными приложениями, которые выполняются в фоновом режиме. Дополнительные сведения о сценарии прямого доступа см. в сценариях Access в платформа удостоверений Майкрософт.

Пошаговое руководство по использованию областей в веб-API см. в статье "Настройка приложения для предоставления веб-API".

Области OpenId Connect

Реализация OpenID Connect на платформе удостоверений Майкрософт имеет несколько четко определенных областей, которые также размещаются в Microsoft Graph: openid, email, profile и offline_access. Области OpenID Connect address и phone не поддерживаются.

Если вы запрашиваете области OpenID Connect и токен, вы получите токен для вызова конечной точки UserInfo.

Область openid

Если приложение выполняет вход с помощью протокола OpenID Connect, оно должно запросить область openid. На странице согласия рабочей учетной записи область openid отображается в виде разрешения Вход от вашего имени.

Это разрешение позволяет приложению получить уникальный идентификатор для пользователя в виде утверждения sub. Оно также предоставляет приложению доступ к конечной точке UserInfo. Область openid может использоваться в конечной точке токена для платформы удостоверений Майкрософт с целью получения токенов идентификации. Приложение может использовать эти токены для проверки подлинности.

Область email

Область email можно использовать вместе с областью openid и любыми другими областями. Она предоставляет приложению доступ к основному электронному адресу пользователя в виде утверждения email.

Утверждение email включается в токен, только если адрес электронной почты связан с учетной записью пользователя (а это не всегда так). Если приложение использует область email, необходимо предусмотреть ситуацию, когда утверждение email отсутствует в токене.

Область profile

Область profile можно использовать вместе с областью openid и любыми другими областями. Она предоставляет приложению доступ к большому объему сведений о пользователе. Информация, доступ к ней может содержать, но не ограничивается именем пользователя, фамилией, предпочитаемым именем пользователя и идентификатором объекта.

Полный список утверждений profile, доступных в параметре id_tokens для конкретного пользователя, представлен в справочнике по id_tokens.

Область offline_access

Область offline_access предоставляет приложению доступ к ресурсам от имени пользователя на длительное время. На странице предоставления согласия эта область отображается в виде разрешения Ведение доступа к данным, к которым вам был предоставлен доступ.

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

Примечание.

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

На платформе удостоверений Майкрософт (запросы к конечной точке версии 2.0) приложение должно явно запросить область offline_access для получения токенов обновления. Поэтому при активации кода авторизации в потоке кода авторизации OAuth 2.0 вы получите только маркер доступа из конечной /token точки.

Маркер доступа обычно действителен около одного часа. На этом этапе приложение должно перенаправить пользователя обратно в /authorize конечную точку, чтобы запросить новый код авторизации. Во время этого перенаправления и в зависимости от типа приложения пользователю может потребоваться снова ввести свои учетные данные или снова предоставить согласие на разрешения.

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

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

  • Требования к области. Убедитесь, что запрашиваются offline_access области вместе с другими необходимыми областями.
  • Тип предоставления авторизации: маркер обновления обычно предоставляется при использовании типа предоставления кода авторизации. Если поток отличается, это может повлиять на ответ.
  • Конфигурация клиента: проверьте параметры приложения на платформе удостоверений. Некоторые конфигурации могут ограничить выдачу refresh_tokens.

Область .default

Область .default используется для предоставления универсальных ссылок на службу ресурса (API) в запросе без указания определенных разрешений. Если требуется согласие, использование .default указывает о необходимости запроса согласия для всех требуемых разрешений, приведенных в регистрации приложения (для всех API в списке).

Значение параметра области создается из URI идентификатора для ресурса и .default, разделенных косой чертой (/). Например, если URI идентификатора ресурса имеет значение https://contoso.com, областью для запроса будет https://contoso.com/.default. В случаях, когда необходимо включить вторую косую черту для правильного запроса токена, см. раздел о замыкающих косых чертах.

Использование scope={resource-identifier}/.default функционально не отличается от использования resource={resource-identifier} на конечной точке v1.0 (где {resource-identifier} — это URI идентификатора для API, например https://graph.microsoft.com для Microsoft Graph).

Область .default можно использовать в любом потоке OAuth 2.0 и для инициирования согласия администратора. Его использование требуется в потоке on-Behalf-Of и потоке учетных данных клиента.

Клиенты не могут объединять статическое (.default) и динамическое согласия в одном запросе. Поэтому scope=https://graph.microsoft.com/.default Mail.Read приводит к ошибке из-за сочетания типов областей.

Параметр .default области активирует только запрос согласия, если согласие не было предоставлено для какого-либо делегированного разрешения между клиентом и ресурсом от имени пользователя, вошедшего в систему.

Если согласие существует, возвращенный маркер содержит все области, предоставленные для этого ресурса для пользователя, вошедшего в систему. Но если для запрашиваемого ресурса не предоставлены разрешения (или если указан параметр prompt=consent), запрос на согласие отображается для всех требуемых разрешений, настроенных в регистрации клиентского приложения, для всех API в списке.

Например, если запрашивается область https://graph.microsoft.com/.default, приложение запрашивает маркер доступа для API Microsoft Graph. Если от имени пользователя, вошедшего в систему, предоставлено по крайней мере одно делегированное разрешение для Microsoft Graph, вход продолжится, а все делегированные разрешения Microsoft Graph, предоставленные для этого пользователя, будут включены в маркер доступа. Если для запрашиваемого ресурса (Microsoft Graph в этом примере) не предоставлены разрешения, запрос на согласие будет представлен для всех требуемых разрешений, настроенных для приложения, для всех API в списке.

Пример 1. Пользователь или администратор клиента предоставил разрешения

В этом примере пользователь или администратор клиента предоставил клиенту разрешения Microsoft Graph Mail.Read и User.Read.

Если клиент запрашивает scope=https://graph.microsoft.com/.default, запрос согласия не отображается независимо от зарегистрированных разрешений клиентского приложения для Microsoft Graph. Возвращаемый токен содержит области Mail.Read и User.Read.

Пример 2. Пользователь не предоставил разрешения между клиентом и ресурсом

В этом примере пользователь (и администратор) не предоставил согласие между клиентом и Microsoft Graph. Клиент зарегистрировал разрешения User.Read и Contacts.Read. Он также зарегистрировал область Azure Key Vault https://vault.azure.net/user_impersonation.

Когда клиент запрашивает маркер для scope=https://graph.microsoft.com/.default, пользователю отображается страница согласия для Microsoft Graph User.Read и областей Contacts.Read, а также для области user_impersonation Azure Key Vault. Возвращаемый маркер содержит только области User.Read и Contacts.Read и может использоваться только с Microsoft Graph.

Пример 3. Пользователь предоставил согласие, а клиент запрашивает дополнительные области

В этом примере пользователь уже предоставил клиенту согласие на разрешение Mail.Read. Клиент зарегистрировал область Contacts.Read.

Сначала клиент выполняет вход с помощью scope=https://graph.microsoft.com/.default. С помощью параметра scopes ответа код приложения определяет, что предоставлено только разрешение Mail.Read. Затем клиент инициирует второй вход с помощью scope=https://graph.microsoft.com/.default и в этот раз принудительно получает согласие с помощью prompt=consent. Если пользователю разрешено предоставить согласие на все разрешения, зарегистрированные приложением, отобразится запрос на согласие. (Если нет, они будут отображаться сообщение об ошибке или форма запроса согласия администратора.) Оба Contacts.Read и Mail.Read будут находиться в запросе на согласие. Если согласие было предоставлено и вход был выполнен, возвращаемый маркер будет предназначаться для Microsoft Graph и включать Mail.Read и Contacts.Read.

.default Использование области с клиентом

В некоторых случаях клиент может запросить собственную область .default. Этот сценарий показан в следующем примере.

// Line breaks are for legibility only.

GET https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
    ?response_type=token            //Code or a hybrid flow is also possible here
    &client_id=00001111-aaaa-2222-bbbb-3333cccc4444
    &scope=9ada6f8a-6d83-41bc-b169-a306c21527a5/.default
    &redirect_uri=https%3A%2F%2Flocalhost
    &state=1234

Этот пример кода создает страницу согласия для всех зарегистрированных разрешений, если предыдущие описания согласия и .default применимы в данном сценарии. Затем код возвращает id_token, а не маркер доступа.

Такая конфигурация не должна использоваться новыми клиентами, предназначенными для платформы удостоверений Майкрософт. Обязательно перейдите в библиотеку проверки подлинности Майкрософт (MSAL) из библиотеки аутентификация Azure AD (ADAL).

Поток предоставления учетных данных клиента и .default

Еще одно назначение .default — запрос ролей приложения (также называются разрешениями приложения) в неинтерактивном приложении, например управляющем, которое использует поток предоставления учетных данных клиента для вызова веб-API.

Сведения об определении ролей приложения (разрешений) для веб-API см. в статье Добавление ролей приложения.

Запросы учетных данных клиента в клиентской службе должны включать scope={resource}/.default. Здесь {resource} — это веб-API, который будет вызываться приложением и для которого оно хочет получить маркер доступа. Отправка запроса учетных данных клиента с помощью отдельных разрешений приложения (ролей) не поддерживается. Все роли приложения (разрешения), предоставленные для этого веб-API, включаются в возвращаемый маркер доступа.

Сведения о предоставлении доступа к определенным ролям приложения, включая предоставление согласия администратора для приложения, см. в статье Настройка клиентского приложения для доступа к веб-API.

Косая черта и .default

В некоторых универсальных кодах ресурса (URI) есть замыкающая косая черта, например https://contoso.com/, а не https://contoso.com. Замыкающая косая черта может вызвать проблемы при проверке токена. Проблемы возникают в основном при запросе токена для Azure Resource Manager (https://management.azure.com/).

В этом случае замыкающая косая черта в коде URI ресурса означает, что при запросе токена должна присутствовать косая черта. Таким образом, при запросе токена для https://management.azure.com/ и использовании .default необходимо запросить https://management.azure.com//.default (обратите внимание на двойную косую черту).

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

См. также