Безопасный доступ к продуктам и API с помощью приложений Microsoft Entra

ОБЛАСТЬ ПРИМЕНЕНИЯ: Разработчик | Базовый | Стандартный | Премия

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

Замечание

В настоящее время приложения находятся в ограниченной предварительной версии. Чтобы зарегистрироваться, заполните эту форму.

С помощью этой функции:

  • Диспетчеры API устанавливают свойство продукта для включения доступа на основе приложений.
  • Диспетчеры API регистрируют клиентские приложения в идентификаторе Microsoft Entra, чтобы ограничить доступ к определенным продуктам.
  • Разработчики могут получить доступ к учетным данным клиентского приложения с помощью портала разработчика службы "Управление API".
  • Используя поток учетных данных клиента OAuth 2.0, разработчики или приложения могут получать токены, которые они включают в запросы API.
  • Токены, представленные в запросах API, проверяются шлюзом управления API для авторизации доступа к API продукта.

Предпосылки

  • Экземпляр управления API, развернутый на уровне "Премиум", "Стандартный", "Базовый" или "Разработчик". Если необходимо развернуть экземпляр службы, см. раздел "Создание экземпляра службы управления API".

  • По крайней мере один продукт в экземпляре службы "Управление API", оснащённый хотя бы одним назначенным ему API.

    • Продукт должен находиться в состоянии публикации , чтобы его могли получить разработчики на портале разработчиков.
    • Для тестирования можно использовать начальный продукт по умолчанию и API эхо , добавленный в него.
    • Если вы хотите создать продукт, см. статью "Создание и публикация продукта".

  • Достаточно разрешений в клиенте Microsoft Entra, чтобы назначить роль администратора приложений , для которой требуется по крайней мере роль администратора привилегированных ролей .

  • При необходимости добавьте одного или нескольких пользователей в экземпляр управления API.

  • Если вы решили использовать Azure PowerShell локально:
    • Установите последнюю версию модуля Az PowerShell.
    • Подключитесь к учетной записи Azure с помощью командлета Connect-AzAccount.
  • Если вы решили использовать Azure Cloud Shell:

Настройка управляемого удостоверения

  1. Включите систему управляемого удостоверения для управления API в вашей системе управления API.

  2. Назначьте идентичность на роль администратора приложения RBAC в Microsoft Entra ID. Чтобы назначить роль, выполните следующие действия.

    1. Войдите на портал и перейдите к идентификатору Microsoft Entra.
    2. В меню слева выберите "Управление>ролями и администраторами".
    3. Выберите администратора приложения.
    4. В меню слева выберите "Управление>назначениями>и добавлением назначений".
    5. На странице Добавление назначений найдите управляемое удостоверение экземпляра API Management по его имени (имя экземпляра API Management). Выберите управляемое удостоверение и нажмите кнопку "Добавить".

Включение доступа через приложение для продукта

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

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

  1. Войдите на портал по следующему пользовательскому URL-адресу функции приложений: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=приложения
  2. Перейдите к вашему экземпляру управления API.
  3. В меню слева в разделе API выберите "Продукты".
  4. Выберите продукт, который требуется настроить, например начальный продукт.
  5. В меню слева в разделе "Продукт" выберите "Свойства".
  6. В разделе доступа на основе приложений включите параметр маркера OAuth 2.0 (наиболее безопасный).
  7. При необходимости включите параметр ключа подписки . Если включить доступ на основе приложений и требование подписки, шлюз управления API может принять маркер OAuth 2.0 или ключ подписки для доступа к API продукта.
  8. Нажмите кнопку "Сохранить".

Снимок экрана: включение доступа на основе приложений на портале.

Подсказка

Вы также можете включить параметр маркера OAuth 2.0 при создании нового продукта.

Включение доступа на основе приложений создает корпоративное серверное приложение в Microsoft Entra ID для репрезентации продукта. Идентификатор внутреннего приложения отображается на странице свойств продукта.

Снимок экрана: параметры приложения продукта на портале.

Замечание

Этот идентификатор приложения задается как значение аудитории при создании клиентского приложения для доступа к продукту. Также используйте это значение при создании маркера для вызова API продукта.

(Необязательно) Просмотр параметров приложения продукта в Microsoft Entra ID

При необходимости просмотрите параметры серверного корпоративного приложения, созданного в идентификаторе Microsoft Entra, чтобы представить продукт.

Приложение называется следующим форматом: APIMProductApplication<product-name>. Например, если имя продукта — Starter, то имя приложения — APIMProductApplicationStarter. Приложение имеет определенную роль приложения .

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

  1. Войдите на портал и перейдите к Microsoft Entra ID>Управление>регистрации приложений.
  2. Выберите все приложения.
  3. Найдите и выберите приложение, созданное службой управления API.
  4. В меню слева в разделе "Управление" выберите роли приложения.
  5. Убедитесь, что роль приложения, заданная управлением API Azure, как показано на следующем снимке экрана:

Снимок экрана: роли приложения на портале.

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

Теперь зарегистрируйте клиентское приложение, которое ограничивает доступ к одному или нескольким продуктам.

  • Продукт должен иметь доступ на основе приложений для связи с клиентским приложением.
  • Каждое клиентское приложение имеет одного пользователя (владельца) в экземпляре службы управления API. Только владелец может получить доступ к API продукта через приложение.
  • Продукт может быть связан с несколькими клиентскими приложениями.

Чтобы зарегистрировать клиентское приложение, выполните действия.

  1. Войдите на портал по следующему пользовательскому URL-адресу функции приложений: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=приложения

  2. Перейдите к вашему экземпляру управления API.

  3. В меню слева в разделе API выберите "Приложения>+ Регистрация приложения".

  4. На странице регистрации приложения введите следующие параметры приложения:

    • Имя — введите имя приложения.
    • Владелец: выберите владельца приложения из раскрывающегося списка пользователей в экземпляре управления API.
    • Предоставление доступа к выбранным продуктам: выберите один или несколько продуктов в экземпляре управления API, которые ранее были включены для доступа на основе приложений.
    • Описание. При необходимости введите описание.

    Снимок экрана: параметры приложения на портале.

  5. Выберите Зарегистрировать.

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

Подсказка

  • После создания приложения при необходимости свяжите его с другими продуктами. Выберите приложение на странице "Приложения" , а затем выберите "Сведения о>продуктах>+ Добавить продукт".
  • Вы также можете создать или связать приложение, изменив продукт на странице "Продукты ".

Создание секрета клиента

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

  1. На странице "Приложения" выберите созданное приложение.

  2. На странице обзора приложения рядом с секретом клиента выберите "Добавить секрет".

  3. На странице "Создать секрет клиента" выберите "Создать".

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

  4. Выберите Закрыть.

(Необязательно) Проверка параметров клиентского приложения в идентификаторе Microsoft Entra

При необходимости просмотрите параметры клиентского приложения в идентификаторе Microsoft Entra.

Приложение называется следующим форматом: APIMApplication<product-name>. Например, если имя продукта — Starter, имя приложения похоже на APIMApplicationStarter.

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

  1. Войдите на портал и перейдите к Microsoft Entra ID>Управление>регистрации приложений.

  2. Выберите все приложения.

  3. Найдите и выберите клиентское приложение, созданное управлением API.

  4. В меню слева в разделе "Управление" выберите разрешения API.

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

    Например, если клиентское приложение предоставляет доступ к продукту Starter , приложение имеет разрешения Product.Starter.All для доступа к приложению APIMProductApplicationStarter .

    Снимок экрана: разрешения API на портале.

Получение параметров приложения на портале разработчика

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

  1. Войдите на портал разработчика (https://<your-apim-instance-name>.developer.azure-api.net) с помощью учетной записи пользователя, которая была задана как владелец клиентского приложения.

  2. В верхнем меню навигации выберите "Приложения".

  3. Приложения, принадлежащие пользователю, отображаются в списке.

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

    Снимок экрана: клиентские приложения на портале разработчика.

Создайте маркер и используйте при вызове API

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

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

Осторожность

Ниже приведены примеры только для тестирования. В рабочей среде используйте безопасный метод для хранения и извлечения секрета клиента.

Вызов клиентского приложения для генерации токена

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

Вызов продуктового API с помощью токена

Маркер, созданный на предыдущем шаге, используется для вызова API продукта. Маркер передается в заголовке авторизации запроса. Инстанс управления API проверяет токен и разрешает доступ к API.

В следующем скрипте показан пример вызова API эхо.

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

Устранение неполадок

Внутренняя ошибка сервера при регистрации приложений на портале

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

  • Роль администратора приложений назначена управляемой идентичности экземпляра управления API в Microsoft Entra ID.
  • Вы вошли на портал по следующему пользовательскому URL-адресу для функции приложений: https://portal.azure.com/?feature.customPortal=false& Microsoft_Azure_ApiManagement=приложения. Этот URL-адрес необходим для доступа к функциям приложений в службе управления API.

Связанный контент

  • Last updated on