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

Краткое руководство. Настройка приложения для предоставления веб-API

  • Статья

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

Необходимые компоненты

Регистрация веб-API

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

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

Выполните действия, описанные в разделе "Регистрация приложения" краткого руководства. Регистрация приложения с помощью платформа удостоверений Майкрософт.

Пропустите раздел URI перенаправления (необязательно). Вам не нужно настраивать URI перенаправления для веб-API, так как пользователи не входят в систему в интерактивном режиме.

Назначение владельца приложения

  1. В разделе "Управление" в разделе "Управление" выберите "Владельцы" и "Добавить владельцев".
  2. В новом окне найдите и выберите владельцев, которые нужно назначить приложению. Выбранные владельцы отображаются на правой панели. После этого подтвердите нажатие кнопки Select. Теперь владельцы приложений будут отображаться в списке владельцев.

Примечание.

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

Назначение роли приложения

  1. В разделе "Управление" в разделе "Управление" выберите роли приложения и создайте роль приложения.

  2. Затем укажите атрибуты роли приложения в области "Создание роли приложения". В этом пошаговом руководстве вы можете использовать примеры значений или указать собственные.

    Поле Описание: Пример
    Отображаемое имя Имя роли приложения Записи сотрудников
    Разрешенные типы элементов Указывает, может ли роль приложения назначаться пользователям, группам и приложениям или приложениям. Приложения
    Value Значение, отображаемое в утверждении "роли" маркера Employee.Records
    Description Более подробное описание роли приложения Приложения имеют доступ к записям сотрудников

  3. Выберите проверка box, чтобы включить роль приложения.

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

Добавление области

Совет

Действия, описанные в этой статье, могут немного отличаться на портале, с который вы начинаете работу.

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

Для начала выполните указанные ниже действия, чтобы создать пример области с именем Employees.Read.All:

  1. Войдите в Центр администрирования Microsoft Entra как минимум облачные приложения Администратор istrator.

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

  3. Перейдите к приложениям> удостоверений>Регистрация приложений и выберите регистрацию приложения API.

  4. Выберите элемент Предоставление API.

  5. Выберите " Добавить рядом с URI идентификатора приложения", если вы еще не настроили его.

    Можно использовать значение по умолчанию api://<application-client-id> или другой поддерживаемый шаблон URI идентификатора приложения. URI идентификатора приложения выступает в качестве префикса для областей, на которые вы будете ссылаться в коде API, и должен быть глобально уникальным.

  6. Щелкните Добавить область.

    An app registration's Expose an API pane in the Azure portal

  7. Затем укажите атрибуты области на панели Добавить панель области. В этом пошаговом руководстве вы можете использовать примеры значений или указать собственные.

    Поле Описание: Пример
    Имя области Имя вашей области. Соглашение об именовании общей области — resource.operation.constraint. Employees.Read.All
    Кто может давать согласие Выберите, могут ли пользователи предоставлять согласие этой области или требуется согласие администратора. Выберите Admins only (Только администраторы) для более высокого уровня разрешений. Администраторы и пользователи
    Отображаемое имя согласия администратора Краткое описание назначения области, которое будут видеть только администраторы. Read-only access to Employee records
    Описание согласия администратора Более детальное описание предоставленного областью разрешения, которое будут видеть только администраторы. Allow the application to have read-only access to all Employee data.
    Отображаемое имя согласия пользователя Краткое описание назначения области. Отображается для пользователей, только если вы задали для параметра Кто может давать согласие значение Admins and users (Администраторы и пользователи). Read-only access to your Employee records
    Описание согласия пользователя Более детальное описание предоставленного областью разрешения. Отображается для пользователей, только если вы задали для параметра Кто может давать согласие значение Admins and users (Администраторы и пользователи). Allow the application to have read-only access to your Employee data.

  8. Задайте параметру Состояние значение Включено, а затем выберите Добавить область.

  9. (Необязательно.) Чтобы отключить запрос согласия пользователей вашего приложения к определенным областям, можно выполнить предварительную авторизацию клиентского приложения для доступа к веб-API. Выполните предварительную авторизацию только тех клиентских приложений, которым вы доверяете, так как у пользователей не будет возможности отклонить согласие.

    1. В разделе Авторизованные клиентские приложения выберите Добавить клиентское приложение.
    2. Введите идентификатор приложения (клиента), для которого хотите выполнить предварительную авторизацию. Например веб-приложение, которое вы зарегистрировали ранее.
    3. В разделе Авторизованные области выберите области, для которых необходимо отключить запрос согласия, а затем щелкните Добавить приложение.

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

Затем добавьте еще один пример области с именем Employees.Write.All, для которого могут предоставлять согласие только администраторы. Области, требующие согласия администратора, обычно используются для предоставления доступа к операциям с более высоким уровнем привилегий. Они также часто используются клиентскими приложениями, которые работают как серверные службы или управляющие программы, которые не поддерживают вход пользователя в интерактивном режиме.

Чтобы добавить пример области Employees.Write.All, выполните действия из раздела Добавление области и укажите эти значения на панели Добавить группу:

Поле Пример значения
Имя области Employees.Write.All
Кто может давать согласие Admins only (Только администраторы)
Отображаемое имя согласия администратора Write access to Employee records
Описание согласия администратора Allow the application to have write access to all Employee data.
Отображаемое имя согласия пользователя Нет (оставить пустым)
Описание согласия пользователя Нет (оставить пустым)

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

Проверка предоставленных областей

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

Screenshot of the Expose an API pane showing two exposed scopes.

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

Например, если URI идентификатора приложения веб-API является https://contoso.com/api, а именем области — Employees.Read.All, полная область будет выглядеть так:

https://contoso.com/api/Employees.Read.All

Использование предоставленных областей

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

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

Позднее вы можете по мере необходимости предоставлять дополнительные области доступа. Помните о том, что веб-API может предоставлять несколько областей, связанных с рядом операций. Ресурс может управлять доступом к веб-API во время выполнения, оценивая утверждения область (scp) в маркере доступа OAuth 2.0, который он получает.

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

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

Краткое руководство. Настройка клиентского приложения для доступа к веб-API