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

The Microsoft identity platform implements the OAuth 2.0 authorization protocol. OAuth 2.0 — это метод, посредством которого стороннее приложение может обращаться к интернет-ресурсам от имени пользователя. Любой веб-размещенный ресурс, который интегрируется с платформой удостоверений Майкрософт, имеет идентификатор ресурса или URI идентификатора приложения.

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

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

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

То же самое относится к любым сторонним ресурсам, которые интегрируются с платформой удостоверений Майкрософт. Любой из этих ресурсов также может определить набор разрешений, разделяющих функциональные возможности этого ресурса на небольшие блоки. As an example, Microsoft Graph defines permissions to do the following tasks, among others:

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

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

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

In OAuth 2.0, these types of permission sets are called scopes. They're also often referred to as permissions. На платформе идентификации Microsoft разрешение представляется в виде строкового значения. Приложение запрашивает необходимые разрешения, указывая разрешение в параметре запроса scope. Платформа идентификации поддерживает несколько четко определенных областей действия OpenID Connect и разрешений на основе ресурсов, каждое разрешение указывается путем присоединения значения разрешения к идентификатору ресурса или URI идентификатора приложения. Например, строка разрешений https://graph.microsoft.com/Calendars.Read используется для запроса разрешения на чтение календарей пользователей в Microsoft Graph.

Admin-restricted permissions

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

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

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

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

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

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

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

If you request the OpenID Connect scopes and a token, you get a token to call the UserInfo endpoint.

Область openid

If an app signs in by using OpenID Connect, it must request the openid scope. Область openid отображается на странице согласия рабочей учетной записи в качестве разрешения на вход в систему.

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

Область email

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

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

Область profile

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

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

Область offline_access

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

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

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

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

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

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

• Scope requirements: Ensure that you're requesting the offline_access scopes along with any other necessary scopes.
• Тип предоставления авторизации: маркер обновления предоставляется при использовании типа предоставления кода авторизации. Если поток отличается, ответ может быть затронут.
• Client configuration: Check your application's settings in the identity platform. Некоторые конфигурации могут ограничить выдачу 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).

The .default scope can be used in any OAuth 2.0 flow and to initiate admin consent. Its use is required in the On-Behalf-Of flow and client credentials flow.

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

.default, когда пользователь дает согласие

Параметр области .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. Этот сценарий показан в следующем примере.

// 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

Another use of .default is to request app roles (also known as application permissions) in a non-interactive application like a daemon app that uses the client credentials grant flow to call a web API.

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

Client credentials requests in your client service must include scope={resource}/.default. Здесь {resource} — это веб-API, который будет вызываться приложением и для которого оно хочет получить маркер доступа. Issuing a client credentials request by using individual application permissions (roles) is not supported. Все роли приложения (разрешения), предоставленные для этого веб-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, который должен принимать его, попробуйте добавить вторую косую черту и повторите попытку.

See also

• Запрос разрешений через согласие на платформе идентификации
• Токены идентификации в платформе удостоверений Microsoft
• Токены доступа в идентификационной платформе Microsoft