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

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

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

• Учетная запись Azure с активной подпиской. Создайте бесплатную учетную запись.
• Завершение краткого руководства. Настройка клиента
• Приложение, зарегистрированное в Центре администрирования Microsoft Entra. Если у вас нет приложения, зарегистрируйте приложение сейчас.

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

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

1. Войдите в Центр администрирования Microsoft Entra как минимум администратор облачных приложений.
2. Если у вас есть доступ к нескольким клиентам, используйте значок "Параметры" в верхнем меню, чтобы переключиться на клиент, содержащий регистрацию приложения из меню каталогов и подписок.
3. Выполните действия, описанные в регистрации приложения, и пропустите раздел URI перенаправления (необязательно). Вам не нужно настраивать URI перенаправления для веб-API, так как пользователи не входят в систему в интерактивном режиме.

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

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

Примечание.

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

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

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

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

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

3. Установите флажок, чтобы включить роль приложения, а затем нажмите кнопку "Применить".

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

Совет

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

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

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

Добавление области, требующей согласия администратора и пользователя

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

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

2. В верхней части страницы нажмите кнопку "Добавить рядом с URI идентификатора приложения". Это значение api://<application-client-id>по умолчанию. URI идентификатора приложения выступает в качестве префикса для областей, на которые вы будете ссылаться в коде API, и должен быть глобально уникальным. Выберите Сохранить.

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

   

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

   Поле	Описание:	Пример
   Имя области	Имя вашей области. Соглашение об именовании общей области — resource.operation.constraint.	Employees.Read.All
   Кто может давать согласие	Выберите, могут ли пользователи предоставлять согласие этой области или требуется согласие администратора. Администраторы должны использоваться только для разрешений с более высоким уровнем привилегий.	Администраторы и пользователи
   Отображаемое имя согласия администратора	Краткое описание назначения области, которое будут видеть только администраторы.	Доступ только для чтения к записям сотрудников
   Описание согласия администратора	Более детальное описание предоставленного областью разрешения, которое будут видеть только администраторы.	Разрешите приложению доступ только для чтения ко всем данным сотрудника.
   Отображаемое имя согласия пользователя	Краткое описание назначения области. Отображается для пользователей, только если вы задали для параметра Кто может давать согласие значение Admins and users (Администраторы и пользователи).	Доступ только для чтения к записям сотрудников
   Описание согласия пользователя	Более детальное описание предоставленного областью разрешения. Отображается для пользователей, только если вы задали для параметра Кто может давать согласие значение Admins and users (Администраторы и пользователи).	Разрешите приложению доступ только для чтения к данным сотрудника.
   Штат	Включена ли область или отключена.	Включено

5. Выберите Добавить область.

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

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

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

Добавление области, требующей согласие администратора

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

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

Поле	Пример значения
Имя области	Employees.Write.All
Кто может давать согласие	Admins only (Только администраторы)
Отображаемое имя согласия администратора	Запись доступа к записям сотрудников
Описание согласия администратора	Разрешить приложению иметь доступ на запись ко всем данным сотрудника.
Отображаемое имя согласия пользователя	Нет (оставить пустым)
Описание согласия пользователя	Нет (оставить пустым)
Штат	Включено

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

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

Полная строка области — это объединение 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