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

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

  • Статья

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

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

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

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

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

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
Параметр Условие Description
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 Значение, включенное в запрос, которое также возвращается в ответе маркера. Это может быть строка любого содержания. Параметр 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 Значение, включенное в запрос, которое также возвращается в ответе маркера. Это может быть строка любого содержания. Параметр state используется для кодирования сведений о состоянии пользователя в приложении перед созданием запроса на аутентификацию, например сведений об открытой на тот момент странице или представлении.
admin_consent Будет иметь значение True, указывающее, что этот ответ произошел в потоке согласия администратора.

Следующие шаги