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

Запрос разрешений с помощью согласия

  • Статья

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

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

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

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

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

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

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

Внимание

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

В запросе авторизации OpenID Подключение или 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. Он позволяет клиенту или приложению правильно идентифицировать пользователя с течением времени и получать доступ к удручаемой информации пользователя.

Снимок экрана, показывающий пример согласия на использование рабочей учетной записи.

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

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

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

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

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

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

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

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

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

Примечание.

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

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

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

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

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

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

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

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

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

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

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

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

Примечание.

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

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

  1. Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.
  2. Перейдите к приложениям >identity>Регистрация приложений> All.
  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 и получении маркеров доступа см. в справочнике по протоколу конечной точки для платформы удостоверений Майкрософт.

См. также