Прочитать на английском

Поделиться через

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

  • Статья

Платформа удостоверений Майкрософт реализует протокол авторизации 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 наборы разрешений такого типа называются областями. Также их часто называют просто разрешениями. На платформе идентификации Microsoft разрешение представляется в виде строкового значения. Приложение запрашивает необходимые разрешения, указывая разрешение в параметре запроса scope. Платформа идентификации поддерживает несколько четко определенных областей действия OpenID Connect и разрешений на основе ресурсов, каждое разрешение указывается путем присоединения значения разрешения к идентификатору ресурса или URI идентификатора приложения. Например, строка разрешений https://graph.microsoft.com/Calendars.Read используется для запроса разрешения на чтение календарей пользователей в Microsoft Graph.

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

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

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

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

Примечание

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

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

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

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

Области применения OpenID Connect

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

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

Область openid

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

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

Область email

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

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

Область profile

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

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

Область offline_access

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

Если предоставлены какие-либо запрошенные делегированные разрешения из параметра scope (за исключением openid, profile, email), это достаточно для того, чтобы приложение запрашивало маркер обновления с помощью offline_access. Например, если разрешение User.Read предоставлено для Майкрософт, приложение получит только токен доступа. Таким образом, если приложение впоследствии запрашивает маркер обновления, тот факт, что User.Read был предоставлен, является достаточным условием для предоставления маркера обновления. Токены обновления имеют длительный срок действия. Приложение может получать новые маркеры доступа после того, как срок действия старых истечет.

Примечание

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

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

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

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

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

  • Требования к областям. Убедитесь, что вы запрашиваете области 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, а также на область https://vault.azure.net/user_impersonation для Azure Key Vault.

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

HTTP 
// 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, вместо маркера доступа.

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

См. также