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

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

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

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

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

  1. Выполните действия, описанные в разделе Регистрация приложениякраткого руководства по регистрации приложения с помощью платформы удостоверений Майкрософт.
  2. Пропустите разделы Добавление URI перенаправления и Настройка параметров платформы. Вам не нужно настраивать URI перенаправления для веб-API, так как пользователи не входят в систему в интерактивном режиме.
  3. Пропустите пока раздел Добавление учетных данных. Если бы ваш API обращался к нисходящему API, ему понадобились бы собственные учетные данные. Такой сценарий не рассматривается в этой статье.

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

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

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

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

  1. Войдите на портал Azure.

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

  3. Выберите Azure Active Directory>Регистрация приложений, а затем — регистрацию приложения API.

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

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

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

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

    Панель

  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, как показано на следующем рисунке:

Снимок экрана: панели

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