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

Согласие администратора на платформе удостоверений Майкрософт

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

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

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

Запрос разрешений от администратора каталога

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

https://login.microsoftonline.com/{tenant}/v2.0/adminconsent
        ?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
        &scope=https://graph.microsoft.com/Calendars.Read https://graph.microsoft.com/Mail.Send
        &redirect_uri=http://localhost/myapp/permissions
        &state=12345
Параметр Состояние Описание
tenant Обязательно Клиент каталога, из которого необходимо запросить разрешение. Можно указать в формате GUID или понятном формате имени ИЛИ, organizations как показано в примере. Не используйте "common", так как личные учетные записи не могут предоставлять согласие администратора, кроме контекста клиента. Чтобы обеспечить лучшую совместимость с личными учетными записями, которые управляют клиентами, по возможности используйте идентификатор клиента.
client_id Обязательно Идентификатор приложения (клиента), который центр администрирования Microsoft Entra — Регистрация приложений присвоил вашему приложению.
redirect_uri Обязательно URI перенаправления, по которому вы хотите, чтобы был отправлен ответ для обработки вашим приложением. Он должен в точности соответствовать одному из универсальных кодов ресурсов (URI) перенаправления, зарегистрированных на портале регистрации приложений.
state Рекомендуется Значение, включенное в запрос, которое также возвращается в ответе маркера. Это может быть строка любого содержания. Используйте параметр state для кодирования сведений о состоянии пользователя в приложении перед выполнением запроса на аутентификацию. Например, это могут быть сведения об открытой на тот момент странице или представлении.
scope Обязательно Определяет набор разрешений, запрашиваемых приложением. Это могут быть статические (с помощью /.default) или динамические области. Это может включать области OIDC (openid, profile, email).

На этом этапе идентификатор Microsoft Entra id требует, чтобы администратор клиента выполнил запрос. Администратору предлагается утвердить все запрошенные разрешения в параметре scope . Если вы использовали статическое (/.default) значение, оно будет работать как конечная точка согласия администратора версии 1.0 и запрашивать согласие для всех областей, найденных в необходимых разрешениях (как для пользователя, так и приложения). Чтобы запросить разрешения приложения, необходимо использовать /.default это значение. Если администраторы не хотят видеть заданное разрешение на экране согласия администратора все время при использовании /.default, рекомендуется не помещать разрешение в раздел необходимых разрешений. Вместо этого можно использовать динамическое согласие для добавления разрешений, которые вы хотите найти на экране согласия во время выполнения, а не с помощью /.default.

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

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

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

Предупреждение

Никогда не используйте значение идентификатораtenant клиента параметра для проверки подлинности или авторизации пользователей. Значение идентификатора клиента можно обновить и отправить плохим субъектам, чтобы олицетворить ответ на приложение. Это может привести к тому, что приложение будет подвержено инцидентам безопасности.

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

http://localhost/myapp/permissions
        ?admin_consent=True
        &error=consent_required
        &error_description=AADSTS65004%3a+The+resource+owner+or+authorization+server+denied+the+request.%0d%0aTrace+ID%3a+0000aaaa-11bb-cccc-dd22-eeeeee333333%0d%0aCorrelation+ID%3a+8478d534-5b2c-4325-8c2c-51395c342c89%0d%0aTimestamp%3a+2019-09-24+18%3a34%3a26Z
        &state=12345

Добавление к параметрам, которые отображаются в успешном ответе, параметры ошибки рассматриваются ниже.

Параметр Описание
error Строка кода ошибки, которая может использоваться для классификации типов возникающих ошибок и может использоваться для реагирования на ошибки.
error_description Определенное сообщение об ошибке, которое может помочь разработчику определить первопричину ошибки.
state Значение, включенное в запрос, которое также будет возвращено в ответе токена. Это может быть строка любого содержания. Состояние используется для кодирования информации о состоянии пользователя в приложении до выполнения запроса аутентификации, например, о странице или представлении, на которых они находились.
admin_consent Будет задано True значение, указывающее, что этот ответ произошел в потоке согласия администратора.

Дальнейшие шаги