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

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

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

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

Замечание

Для приложений во внешних арендаторах пользователи не могут самостоятельно давать согласие на разрешения. Администратору потребуется предоставить приложению согласие на доступ к ресурсам от их имени. Дополнительные сведения см. в разделе "Предоставление согласия администратора".

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

Статические разрешения также позволяют администраторам предоставлять согласие от имени всех пользователей в организации.

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

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

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

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

Это важно

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

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

В запросе авторизации OpenID Connect или OAuth 2.0 приложение может запрашивать необходимые разрешения с помощью scope параметра запроса. Например, когда пользователь входит в приложение, приложение отправляет запрос, как показано в следующем примере. (Разрывы строк добавляются для удобочитаемости).

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=
https%3A%2F%2Fgraph.microsoft.com%2Fcalendars.read%20
https%3A%2F%2Fgraph.microsoft.com%2Fmail.send
&state=12345

Параметр scope — это разделенный пробелом список делегированных разрешений, запрашиваемых приложением. Чтобы указать каждое разрешение, его значение добавляется к идентификатору ресурса (универсальному коду ресурса (URI) идентификатора приложения). В примере запроса приложению требуется разрешение на чтение календаря пользователя и отправку почты от имени пользователя.

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

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

Разрешение offline_access предоставляет приложению доступ к маркерам обновления, которые критически важны для собственных приложений и веб-приложений. Разрешение User.Read предоставляет доступ к заявке sub. Он позволяет клиенту или приложению правильно идентифицировать пользователя с течением времени и получать доступ к основной информации пользователя.

Пример снимка экрана, на котором показано согласие рабочей учетной записи.

Когда пользователь утвердит запрос на разрешение, будет записано согласие. Пользователю не нужно снова предоставлять согласие при входе в приложение.

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

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

Администраторы, использующие то же приложение, видят запрос согласия администратора. Запрос согласия администратора предоставляет флажок, позволяющий им предоставлять приложению доступ к запрошенным данным от имени пользователей для всего клиента. Дополнительные сведения об интерфейсе согласия пользователя и администратора см. в разделе "Согласие приложений".

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

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

Полный список разрешений Microsoft Graph см. в справочнике по разрешениям Microsoft Graph.

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

Некоторые организации могут изменить политику согласия пользователя по умолчанию для клиента. Когда ваше приложение запрашивает доступ к разрешениям, их оценивают в соответствии с указанными политиками. Пользователю может потребоваться запросить согласие администратора, даже если это не требуется по умолчанию. Сведения о том, как администраторы управляют политиками согласия для приложений, см. в статье "Управление политиками согласия приложений".

Замечание

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

Разрешения приложения всегда требуют согласия администратора. Разрешения приложения не имеют контекста пользователя, и предоставление согласия не выполняется от имени какого-либо конкретного пользователя. а напрямую клиентскому приложению. Эти типы разрешений используются только службами управляющей программы и другими неинтерактивными приложениями, которые выполняются в фоновом режиме. Администраторы должны настроить разрешения заранее и предоставить согласие администратора через Центр администрирования Microsoft Entra.

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

Администратор может предоставить согласие для приложения со следующими параметрами.

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

  • Часть процесса регистрации в приложении.
  • Часть параметров приложения.
  • Выделенный процесс подключения.

Во многих случаях приложение может показать представление "connect" только после входа пользователя с рабочей учетной записью Майкрософт или учебной учетной записью Майкрософт.

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

Чтобы войти в систему, следуйте инструкциям по протоколу платформы управления идентификацией Microsoft.

Запрос разрешений на портале регистрации приложения

На портале регистрации приложений приложения могут перечислять необходимые разрешения, включая делегированные разрешения и разрешения приложения. Эта настройка позволяет использовать область .default и параметр Предоставить согласие администратора Центра администрирования Microsoft Entra.

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

Замечание

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

Чтобы настроить список статически запрошенных разрешений для приложения:

  1. Войдите в Центр администрирования Microsoft Entra как минимум администратор облачных приложений.
  2. Перейдите в Entra ID>, затем выберите Регистрация приложений> и Все приложения.
  3. Выберите приложение или создайте приложение , если вы еще не сделали этого.
  4. На странице обзора приложения в разделе "Управление" выберите "Разрешения> API" "Добавить разрешение".
  5. Выберите Microsoft Graph из списка доступных API. Затем добавьте разрешения, необходимые вашему приложению.
  6. Выберите "Добавить разрешения".

Успешный ответ

Если администратор утверждает разрешения для приложения, успешный ответ выглядит следующим образом:

GET http://localhost/myapp/permissions?tenant=aaaabbbb-0000-cccc-1111-dddd2222eeee&state=state=12345&admin_consent=True
Параметр Описание
tenant Арендатор каталога, предоставивший вашему приложению запрошенные разрешения, в формате GUID.
state Значение, включенное в запрос, возвращаемое в ответе токена. Это может быть строка любого содержания. Состояние используется для кодирования сведений о состоянии пользователя в приложении до запроса аутентификации, например, о странице или виде, на котором они находились.
admin_consent Задано значение True.

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

Ответ на ошибку

Если администратор не утвердит разрешения для приложения, ответ с ошибкой выглядит следующим образом:

GET http://localhost/myapp/permissions?error=permission_denied&error_description=The+admin+canceled+the+request
Параметр Описание
error Строка кода ошибки, которую можно использовать для классификации типов ошибок, возникающих. Его также можно использовать для реагирования на ошибки.
error_description Определенное сообщение об ошибке, которое может помочь разработчику определить первопричину ошибки.

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

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

{
    "grant_type": "authorization_code",
    "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
    "scope": "https://microsoft.graph.com/Mail.Read https://microsoft.graph.com/mail.send",
    "code": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...",
    "redirect_uri": "https://localhost/myapp",
    "client_secret": "A1bC2dE3f..."  // NOTE: Only required for web apps
}

Полученный маркер доступа можно использовать в HTTP-запросах к ресурсу. Он надежно указывает ресурсу, которому ваше приложение имеет надлежащее разрешение на выполнение определенной задачи.

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

Связанный контент

  • Last updated on