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

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

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

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

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

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

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

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

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

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

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

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

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

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