Раскрытие областей доступа в защищенном веб-API

Применяется к: Арендаторы рабочей области (дополнительные сведения)

В этой статье объясняется, как добавить области в приложение для защищенного веб-API.

Предпосылки

• Зарегистрируйте новое приложение в Центре администрирования Microsoft Entra, настроенное только для учетных записей в этом каталоге организации. Дополнительные сведения см. в статье "Регистрация приложения ". Запишите следующие значения на странице обзора приложения для последующего использования:
  • Идентификатор приложения (клиента)
  • Идентификатор каталога (арендатора)

Области и URI идентификатора приложения

Области обычно имеют следующую форму: resourceURI/scopeName. В Microsoft Graph области имеют ярлыки. Например, User.Read является ярлыком для https://graph.microsoft.com/user.read.

Во время регистрации приложения необходимо определить следующие параметры:

• URI ресурса
• Одна или несколько областей
• Одна или несколько ролей приложений

По умолчанию для портала регистрации приложений рекомендуется использовать универсальный код ресурса (URI) api://{clientId}. Этот URI уникален, но не может быть прочитан человеком. При изменении URI убедитесь, что его новое значение уникально. Портал регистрации приложений гарантирует, что используется настроенный домен издателя.

Для клиентских приложений области отображаются как делегированные права доступа, а роли приложений отображаются как права доступа приложений в веб-API.

Области (права доступа) также отображаются в окне согласия, которое представлено пользователям вашего приложения. Поэтому необходимо предоставить соответствующие строки, описывающие область:

• Как они видны пользователю.
• Как это видит администратор арендатора, который может предоставить согласие администратора.

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

Открыть доступ к делегированным разрешениям (сферы)

Чтобы предоставить делегированные разрешения (области), выполните действия, описанные в разделе Настройка приложения для предоставления веб-API.

Если вы работаете в рамках сценария применения веб-API, описанного в этом наборе статей, используйте следующие параметры:

• URI идентификатора приложения: примите предложенный URI идентификатора приложения (api://< clientId>) (если будет предложено).
• Имя области: access_as_user.
• Кто может давать согласие : Администраторы и пользователи.
• Отображаемое имя согласия администратора: Доступ к TodoListService в качестве пользователя.
• Описание согласия администратора: Доступ к веб-API TodoListService в качестве пользователя.
• Отображаемое имя согласия пользователя: Доступ к TodoListService в качестве пользователя.
• Описание согласия пользователя: Доступ к веб-API TodoListService в качестве пользователя.
• Состояние: включено

Если веб-API вызывается службой или демон-приложением

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

Открывать доступ к разрешениям приложения (роли в приложении)

Чтобы предоставить разрешения приложения, выполните действия, описанные в разделе Добавление ролей приложения в приложение.

В области Создание роли приложения в разделе Разрешенные типы элементов выберите Приложения. Вы также можете добавить роль с помощью редактора манифеста приложения, как описано в статье.

Ограничьте маркеры доступа для определенных клиентских приложений

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

Чтобы добавить еще один уровень безопасности, администратор клиента Microsoft Entra может настроить свой клиент, чтобы платформа удостоверений Майкрософт выдает маркеры безопасности только клиентским приложениям, которым администратор клиента одобрил доступ к API.

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

1. В Центре администрирования Microsoft Entra выберите ваше приложение в разделе Entra ID>.
2. На странице Обзор приложения в разделе Основные сведения найдите и выберите ссылку Управляемое приложение в локальном каталоге, чтобы перейти на страницу Обзор корпоративного приложения.
3. В разделе Управление выберите Свойства.
4. Установите Требуется назначение? в Да.
5. Нажмите кнопку "Сохранить".

Теперь Microsoft Entra ID будет проверять назначения ролей клиентских приложений, запрашивающих токены доступа для вашего веб-API. Если клиентскому приложению не назначены роли приложения, Microsoft Entra ID возвращает клиенту сообщение об ошибке, подобное _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

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

Следующая статья в этой серии —Конфигурация кода приложения.