Защищенный веб-API: регистрация приложения

  • Статья

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

С общими инструкциями по регистрации приложения можно ознакомиться в статье Начало работы: Регистрация приложения с помощью платформы удостоверений Microsoft.

Принятая версия маркера

Платформа удостоверений Microsoft может предоставлять маркеры версий 1.0 и 2.0. Дополнительные сведения об этих маркерах см. в статье Маркеры доступа.

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

  • Если для параметра Поддерживаемые типы учетных записей указано значение Учетные записи в любом каталоге организации и личные учетные записи Майкрософт (например, Skype, Xbox, Outlook.com), принятой версией маркера должна быть версия 2.0.
  • В противном случае принятой версией маркера может быть только версия 1.0.

Определить или изменить принятую версию маркера после создания приложения можно с помощью следующих действий:

  1. На портале Azure выберите приложение и щелкните Манифест.
  2. Найдите в манифесте свойство accessTokenAcceptedVersion.
  3. Значение указывает Microsoft Entra, какая версия маркера принимает веб-API.
    • Если это значение равно 2, веб-API принимает маркеры версии 2.0.
    • Если это значение равно null, веб-API принимает маркеры версии 1.0.
  4. Если вы изменили версию маркера, то после изменения нажмите кнопку Сохранить.

Веб-API указывает, какая версия маркера принимается. Когда клиент запрашивает маркер для веб-API через платформу удостоверений Microsoft, клиенту предоставляется маркер, указывающий, какая версия маркера принимается веб-API.

URI перенаправления не используются

Для веб-API интерфейсов не нужно регистрировать URI перенаправления, так как пользователь входит в систему в интерактивном режиме.

Предоставляемый API

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

Области и 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 в качестве пользователя.
  • Состояние: включено

Совет

Для универсального кода ресурса (URI) идентификатора приложения можно задать для него физический центр API, напримерhttps://graph.microsoft.com. Это может быть полезно, если URL-адрес API, который необходимо вызвать, известен.

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

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

Предоставление разрешений приложения (роли приложений)

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

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

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

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

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

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

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

Идентификатор Microsoft Entra теперь проверка для назначений ролей приложений клиентских приложений, запрашивающих маркеры доступа для веб-API. Если клиентское приложение не назначено ни одной роли приложения, идентификатор Microsoft Entra возвращает клиенту сообщение об ошибке, аналогичное invalid_client: AADSTS501051: <имя> приложения не назначается роли для <веб-API>.

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

НЕ ИСПОЛЬЗУЙТЕ коды ошибок AADSTS и соответствующие строки сообщений в качестве литералов в коде приложения. Коды ошибок AADSTS и строки сообщения об ошибке, возвращаемые идентификатором Microsoft Entra, не являются неизменяемыми и могут быть изменены корпорацией Майкрософт в любое время и без ваших знаний. Если вы принимаете решения о ветвлении в коде на основе значений кодов AADSTS или соответствующих строк сообщений, функциональность и стабильность приложения не гарантируются.

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

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