Авторизация тестовой консоли портала разработчика путем настройки авторизации пользователя с помощью OAuth 2.0

Статья
04/01/2024

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

Настройка авторизации пользователя OAuth 2.0 в тестовой консоли портала разработчика предоставляет разработчикам удобный способ для получения маркера доступа OAuth 2.0. Из тестовой консоли маркер просто передается в серверную часть с помощью вызова API. Проверку маркеров нужно настроить отдельно — либо с помощью политики проверки JWT, либо в серверной службе.

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

В этой статье объясняется, как настроить экземпляр службы "Управление API" на использование авторизации OAuth 2.0 в тестовой консоли портала разработчика, но не объясняется, как настроить поставщика OAuth 2.0.

Если экземпляр службы управления API еще не создан, см. статью Создание экземпляра службы управления API Azure.

Обзор сценария

Настройка авторизации пользователя OAuth 2.0 в Управление API включает только тестовую консоль портала разработчика (и тестовую консоль в портал Azure) в качестве клиента для получения маркера с сервера авторизации. Настройка для каждого поставщика OAuth 2.0 имеет свои особенности, хотя инструкции в целом схожи, а данные, необходимые для настройки этого протокола в экземпляре службы "Управление API", одинаковы. В этой статье показан пример использования идентификатора Microsoft Entra в качестве поставщика OAuth 2.0.

Ниже приведены этапы настройки высокого уровня:

Регистрация приложения (серверного приложения) в Microsoft Entra ID для представления API.
Зарегистрируйте другое приложение (клиентское приложение) в идентификаторе Microsoft Entra, чтобы представить клиентское приложение, которое должно вызывать API- в данном случае тестовую консоль портала разработчика.

Предоставление разрешения в Microsoft Entra ID, чтобы разрешить клиентскому приложению вызывать серверное.
Настройте тестовую консоль на портале разработчика для вызова API с использованием авторизации пользователя с помощью OAuth 2.0.
Настройте API для авторизации пользователей с помощью OAuth 2.0.
Добавьте политику для предварительной авторизации маркера OAuth 2.0 для каждого входящего запроса. Политику можно использовать validate-jwt для любого поставщика OAuth 2.0.

Эта конфигурация поддерживает следующий поток OAuth:

Обзор рисунка для визуального представления следующего потока.

Портал разработчика запрашивает маркер из идентификатора Microsoft Entra с помощью учетных данных клиентского приложения.
После успешной проверки идентификатор Microsoft Entra выдает маркер доступа и обновления.
Разработчик (пользователь портала разработчика) вызывает API с заголовком авторизации.
Маркер проверяется с помощью validate-jwt политики в Управление API идентификатором Microsoft Entra.
На основе результата проверки разработчик получит ответ на портале разработчика.

Типы предоставления авторизации

Управление API Azure поддерживает следующие типы предоставления разрешений (потоки) для OAuth 2.0. Тип предоставления разрешения — это способ клиентского приложения (в этом контексте — тестовая консоль на портале разработчика) для получения маркера доступа для внутреннего API. Вы можете настроить один или несколько типов предоставления разрешения в зависимости от поставщика и сценариев OAuth 2.0.

Ниже приведена краткая сводка. Дополнительные сведения о типах предоставления разрешения см. на страницах OAuth 2.0 Authorization Framework и типов предоставления разрешения OAuth.

Тип предоставления разрешения	Description	Сценарии
Код авторизации	Обменивает код авторизации на маркер	Приложения на стороне сервера, например веб-приложения
Код авторизации + PKCE	Усовершенствование потока кода авторизации, создающего вызов кода, отправляемый с помощью запроса авторизации	Мобильные и общедоступные клиенты, которые не могут защитить секрет или токен
Неявное (не рекомендуется)	Возвращает маркер доступа немедленно без дополнительного шага обмена кодом авторизации	Клиенты, которые не могут защитить секрет или маркер, такие как мобильные приложения и одностраничные приложения Как правило, не рекомендуется из-за неотъемлемых рисков возврата маркера доступа при перенаправлении HTTP без подтверждения его получения клиентом.
Пароль владельца ресурса	Запрашивает учетные данные пользователя (имя пользователя и пароль), обычно с помощью интерактивной формы	Для использования с приложениями с высоким уровнем доверия Следует использовать только при невозможности использовать другие, более безопасные потоки
Учетные данные клиента	Аутентифицирует и авторизует приложение, а не пользователя	Приложения, передающие данные между компьютерами, которым не требуются разрешения конкретного пользователя на доступ к данным, такие как CLI, управляющие программы или службы, работающие в серверной части.

Вопросы безопасности

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

При настройке авторизации пользователя OAuth 2.0 в тестовой консоли портала разработчика сделайте следующее:

Сделайте область маркера минимальной для тестирования API разработчиками. Ограничьте область до тестовой консоли или затронутых API. Действия по настройке области маркера зависят от поставщика OAuth 2.0.

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

Отслеживание ключевых сведений

В этом руководстве вам будет предложено записать ключевые сведения для последующего использования:

Идентификатор внутреннего приложения (клиента): GUID приложения, представляющего API серверной части
Области внутренних приложений: одна или несколько областей, которые можно создать для доступа к API. Формат области — api://<Backend Application (client) ID>/<Scope Name> (например,api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
Идентификатор клиентского приложения (клиента): GUID приложения, представляющего портал разработчика
Значение секрета клиентского приложения: ИДЕНТИФИКАТОР GUID, который служит секретом для взаимодействия с клиентским приложением в идентификаторе Microsoft Entra

Регистрация приложений на сервере OAuth

Вам потребуется зарегистрировать два приложения у вашего поставщика OAuth 2.0: одно представляет серверный API, который нужно защитить, а второе — клиентское приложение, которое вызывает API, в нашем примере это тестовая консоль портала разработчика.

Ниже приведены примеры действий, использующих идентификатор Microsoft Entra в качестве поставщика OAuth 2.0. Дополнительные сведения о регистрации приложений см. в разделе Краткое руководство. Настройка приложения для предоставления доступа к веб-API.

Регистрация приложения в идентификаторе Microsoft Entra для представления API

На портале Azure найдите и выберите Регистрация приложений.
Выберите Создать регистрацию.
Когда появится страница Регистрация приложения, введите регистрационную информацию приложения:
- В разделе Имя введите понятное имя приложения, которое будет отображаться пользователям приложения, например backend-app.
- В разделе Поддерживаемые типы учетных записей выберите вариант, который подходит для вашего сценария.
Оставьте раздел URI перенаправления пустым. Позже вы добавите URI перенаправления, созданный в конфигурации OAuth 2.0 в Управлении API.
Выберите Зарегистрировать, чтобы создать приложение.
На странице приложения Обзор найдите идентификатор приложения (клиента) и запишите его, чтобы использовать позже.
В разделе Управление бокового меню выберите Предоставление API и задайте для параметра URI идентификатора приложения значение по умолчанию. Это значение необходимо для дальнейшей работы.
Нажмите кнопку Добавить область, чтобы открыть страницу Добавление области:
1. Введите имя области для область, поддерживаемой API (например, Files.Read).
2. В Кто может предоставить согласие?выберите сценарий, например Администратор и пользователей. Выберите Администратор только для более высоких привилегированных сценариев.
3. Введите отображаемое имя согласия Администратор и описание согласия Администратор.
4. Убедитесь, что выбрано состояние области Включено.
Нажмите кнопку Добавить область, чтобы создать область.
Повторите предыдущие два шага, чтобы добавить все области, поддерживаемые API.
Созданные области понадобятся на следующем шаге.

Регистрация другого приложения в идентификаторе Microsoft Entra для представления клиентского приложения

Зарегистрируйте каждое клиентское приложение, которое вызывает API в качестве приложения в идентификаторе Microsoft Entra.

На портале Azure найдите и выберите Регистрация приложений.
Выберите Создать регистрацию.
Когда появится страница Регистрация приложения, введите регистрационную информацию приложения:
- В разделе Имя введите понятное имя приложения, которое будет отображаться пользователям приложения, например client-app.
- В разделе Поддерживаемые типы учетных записей выберите вариант, который подходит для вашего сценария.
В разделе URI перенаправления выберите Веб-адрес и оставьте поле URL-адреса пустым.
Выберите Зарегистрировать, чтобы создать приложение.
На странице приложения Обзор найдите идентификатор приложения (клиента) и запишите его, чтобы использовать позже.
Создайте секрет клиента для этого приложения. Он будет использоваться на следующем шаге.
1. В разделе "Управление" бокового меню выберите сертификаты и секреты.
2. В разделе Секреты клиента выберите + Новый секрет клиента.
3. В разделе Добавление секрета клиента укажите описание и выберите срок действия ключа.
4. Выберите Добавить.

Значение ключа созданного секрета понадобится на следующем шаге. Вы не сможете больше получить доступ к секрету на портале.

Предоставление разрешений в идентификаторе Microsoft Entra

Теперь, когда вы зарегистрировали два приложения для представления API и консоли разработчика, предоставьте разрешения, позволяющие клиентскому приложению вызывать серверное приложение.

На портале Azure найдите и выберите Регистрация приложений.
Выберите свое клиентское приложение. Затем в боковом меню выберите Разрешения API.
Щелкните + Добавить разрешение.
В разделе Выбор API выберите Мои API, а затем найдите и выберите серверное приложение.
Выберите Делегированные разрешения, затем выберите соответствующие разрешения для серверного приложения.
Выберите Добавить разрешения.

Необязательно.

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

Настройка сервера авторизации OAuth 2.0 в управлении API

Перейдите к экземпляру Управления API на портале Azure.
В разделе "Портал разработчика" в боковом меню выберите OAuth 2.0 + OpenID Подключение.
На вкладке OAuth 2.0 щелкните + Добавить.
В полях Имя и Описание введите имя и (при желании) описание.

Примечание.

Эти поля служат для идентификации сервера авторизации OAuth 2.0 в текущей службе "Управление API". Их значения принимаются не с сервера OAuth 2.0.
Введите URL-адрес страницы регистрации клиента, например https://contoso.com/login. Эта страница позволяет пользователям создавать учетные записи и управлять ими, если поставщик OAuth 2.0 поддерживает управление учетными записями пользователей. Страница зависит от используемого поставщика OAuth 2.0.

Если у вашего поставщика OAuth 2.0 не настроено пользовательское управление учетными записями, введите здесь URL-адрес-заполнитель, например URL-адрес вашей компании или URL-адрес http://localhost.
В следующем разделе формы содержатся параметры Типы предоставления авторизации, URL-адрес конечной точки авторизации и Метод запроса авторизации.
- Выберите один или несколько требуемых типов предоставления авторизации. В этом примере выберите Код авторизации (вариант по умолчанию). Подробнее
- Введите URL-адрес в поле Authorization endpoint URL. URL-адрес конечной точки можно получить на странице Конечные точки одной из регистраций приложения. Для однотенантного приложения в идентификаторе Microsoft Entra этот URL-адрес будет похож на один из следующих URL-адресов, где {aad-tenant} заменяется идентификатором клиента Microsoft Entra.
  
  Рекомендуется использовать конечную точку версии 2, но Управление API поддерживает конечные точки версии 1 и 2.
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (версия 2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (версия 1)
- Параметр Authorization request method указывает на то, каким образом запрос авторизации отправляется на сервер OAuth 2.0. Выберите POST.
Укажите URL-адрес конечной точки маркера, методы проверки подлинности клиента, метод отправки маркера доступа и область по умолчанию.
- Укажите URL-адрес конечной точки маркера. Для одного приложения клиента в идентификаторе Microsoft Entra он будет похож на один из следующих URL-адресов, где {aad-tenant} заменяется идентификатором клиента Microsoft Entra. Используйте ту же версию конечной точки (версия 2 или 1), которую вы выбрали ранее.
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (версия 2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/token (версия 1)
- При использовании конечных точек версии 1 добавьте параметр тела:
  * Name: ресурс.
  * Value: идентификатор приложения (клиента) серверного приложения.
- При использовании конечных точек версии 2, сделайте следующее:
  * Используйте область внутреннего приложения, созданную в поле Область по умолчанию.
  * Задайте для свойства accessTokenAcceptedVersion значение 2 в манифесте приложения для серверного приложения и регистраций клиентских приложений.
- Примите параметры по умолчанию в полях Методы проверки подлинности клиента и Метод отправки маркера доступа.
В учетных данных клиента введите идентификатор клиента и секрет клиента, полученный во время создания и настройки клиентского приложения.
После определения значений в полях Идентификатор клиента и Секрет клиента генерируется параметр URI перенаправления для кода авторизации. Этот URI используется для настройки URL-адреса перенаправления в конфигурации сервера OAuth 2.0.

На портале разработчика суффикс URI имеет вид:
- /signin-oauth/code/callback/{authServerName} для потока предоставления кода авторизации
- /signin-oauth/implicit/callback для неявного потока предоставления
Скопируйте соответствующий URI перенаправления на страницу Проверка подлинности регистрации клиентского приложения. В регистрации приложения выберите "Аутентификация>+ Добавить веб-сайт платформы>" и введите универсальный код ресурса (URI перенаправления).
Если для параметра Типы предоставления авторизации задано значение Пароль владельца ресурса, то в разделе Учетные данные владельца ресурса нужно указать соответствующие учетные данные. В противном случае эти поля можно оставить пустыми.
Выберите Создать, чтобы сохранить конфигурацию сервера авторизации OAuth 2.0 для службы "Управление API".
Повторно опубликуйте портал разработчика.

Внимание

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

Настройка API для авторизации пользователей по протоколу OAuth 2.0

После сохранения конфигурации сервера OAuth 2.0 настройте API или API для использования этой конфигурации.

Внимание

Настройка параметров авторизации пользователей OAuth 2.0 для API позволяет Управление API получать маркер с сервера авторизации при использовании тестовой консоли на портал Azure или портале разработчика. Параметры сервера авторизации также добавляются в определение и документацию ПО API.
Для авторизации OAuth 2.0 во время выполнения клиентское приложение должно получить и представить маркер и настроить проверку маркера в Управление API или серверном API. Пример см. в статье "Защита API в Azure Управление API с помощью авторизации OAuth 2.0 с идентификатором Microsoft Entra.

В меню Управление API слева выберите API.
Выберите имя нужного API и перейдите на вкладку Параметры. Прокрутите страницу до раздела Безопасность и выберите OAuth 2.0.
В раскрывающемся списке Сервер авторизации выберите нужный пункт и нажмите кнопку Сохранить.

Портал разработчика. Тестирование авторизации пользователя OAuth 2.0

Настроив сервер авторизации OAuth 2.0 и его использование интерфейсом API, вы можете протестировать сервер, перейдя на портал разработчика и вызвав API.

Выберите Портал разработчика в верхнем меню страницы Обзор экземпляра службы "Управление API" Azure.
Перейдите к любой из операций в разделе API на портале разработчика.
Выберите Попробовать, чтобы открыть консоль разработчика.
Обратите внимание на новый элемент в разделе Авторизация, соответствующий только что добавленному серверу авторизации.
Выберите Код авторизации в раскрывающемся списке авторизации.
После запроса войдите в клиент Microsoft Entra.
- Если вы уже вошли в учетную запись, запрос может не отобразиться.
После успешного входа Authorization в запрос добавляется заголовок с маркером доступа из идентификатора Microsoft Entra. Ниже приведен краткий пример маркера (в кодировке Base64):
```
Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
```
Настройте требуемые значения для оставшихся параметров и нажмите кнопку "Отправить ", чтобы вызвать API.

Настройка политики проверки JWT для запросов предварительной авторизации

В конфигурации до сих пор Управление API не проверяет маркер доступа. Она только передала маркер в заголовке авторизации серверному API.

Для предварительной авторизации запросов настройте политику validate-jwt для проверки маркера доступа каждого входящего запроса. Если у запроса нет допустимого маркера, Управление API заблокирует его.

В следующем примере политики при добавлении <inbound> в раздел политики проверка значение утверждения аудитории в маркере доступа, полученном из идентификатора Microsoft Entra, представленного в заголовке авторизации. Он возвращает сообщение об ошибке, если маркер не действителен. Настройте эту политику в области политики, соответствующей вашему сценарию.

В URL-адресе openid-configaad-tenant — это идентификатор клиента в идентификаторе Microsoft Entra. Найдите это значение в портал Azure, например на странице обзора ресурса Microsoft Entra. В приведенном примере предполагается однотенантное приложение Microsoft Entra и конечная точка конфигурации версии 2.
Значением claim является идентификатор клиента серверного приложения, зарегистрированного в идентификаторе Microsoft Entra.

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

Примечание.

Указанный выше URL-адрес openid-config соответствует конечной точке версии 2. Для конечной точки версии 1 openid-config используйте https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration.

Сведения о настройке политик см. в статье How to set or edit Azure API Management policies (Как настроить или изменить политики в службе управления API Azure). Дополнительные сведения о настройке для проверки JWT см. в справочнике по validate-jwt . Чтобы проверить JWT, предоставляемый службой Microsoft Entra, Управление API также предоставляет validate-azure-ad-token политику.

Дополнительные сведения об использовании OAuth 2.0 и Управление API см. в статье "Защита серверной части веб-API в Azure" Управление API с помощью авторизации OAuth 2.0 с идентификатором Microsoft Entra.
Дополнительные сведения о потоке кода авторизации платформа удостоверений Майкрософт и OAuth 2.0