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

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

Предварительные условия

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

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

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

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

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

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

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

1. В вашей регистрации приложения, в разделе Управление, выберите Роли приложения и Создать роль приложения.

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

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

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Добавление области" и укажите эти значения в области "Добавление области". Нажмите кнопку "Добавить область " после завершения:

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

Если вы успешно добавили оба примера областей, описанных в предыдущих разделах, они будут отображаться в разделе Предоставление 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, настроив его области, выполните настройку регистрации клиентского приложения с разрешением на доступ к этим областям.