Поделиться через

Подписки в службе управления API Azure

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни управления API

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

Примечание.

Подписка на Управление API используется для вызова API с помощью ключа подписки. Это не так же, как подписка Azure.

Что такое подписки?

При публикации API-интерфейсов в Управлении API использование ключей подписки является самым простым способом защиты доступа к этим интерфейсам. Разработчики, которым требуется использовать опубликованные API, должны включать действительный ключ подписки в HTTP-запросах при выполнении вызовов к этим API. Без использования действительного ключа подписки вызовы:

  • Они были немедленно отклонены шлюзом Управления API.
  • Не пересылается в серверную часть.

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

Кроме того, примите во внимание следующее:

  • Разработчики могут получать подписки, не требуя утверждения от издателей API.
  • Издатели API могут самостоятельно создавать подписки напрямую для пользователей API.

Совет

Управление API поддерживает также другие механизмы для защиты доступа к API, среди них:

Управление ключами подписки

Регулярное повторное создание ключей является общей мерой безопасности. Как и большинство служб Azure, которым требуется ключ подписки, Управление API создает ключи в парах. Каждое приложение, использующее службу, может переключиться с ключа A на ключ B и повторно создать ключ A с минимальным нарушением работы службы, и наоборот.

Установка определенных ключей вместо их повторного создания может быть выполнена путем вызова Azure API Management Subscription - Create Or Update Azure REST API. В частности, properties.primaryKey и/или properties.secondaryKey необходимо установить в теле HTTP-запроса.

Примечание.

  • Управление API не предоставляет встроенные функции для управления жизненным циклом ключей подписки, таких как настройка дат окончания срока действия или автоматическое поворот ключей. Вы можете разрабатывать рабочие процессы для автоматизации этих процессов с помощью таких средств, как Azure PowerShell или пакеты SDK Azure.
  • Чтобы обеспечить ограниченный доступ к API, издатели API могут использовать политики с ключами подписки или использовать механизм, обеспечивающий встроенный срок действия, например проверку подлинности на основе маркеров.

Область подписок

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

Подписки для продукта

Традиционно подписки в Управлении API связывались с одной областью продукта API. Разработчики:

  • Нашел список продуктов на портале разработчика.
  • отправляют запросы на подписку на продукт, который желают использовать;
  • используют ключи в этих подписках (утвержденные либо автоматически, либо издателями API) для доступа ко всем API в продукте.

В настоящее время на портале разработчика отображаются только подписки для области продуктов в разделе Профиль пользователя.

Подписки для продукта

Подписки для всех API или отдельных API

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

  • Один API или
  • все API в экземпляре управления API.

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

Подписка "Полный доступ"

Каждый экземпляр API Management поставляется со встроенной подпиской с полным доступом, которая предоставляет доступ ко всем API. Эта подписка, ограниченная областью службы, позволяет владельцам служб легко тестировать и отлаживать API в тестовой консоли.

Предупреждение

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

Примечание.

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

Автономные подписки

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

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

  • Поделитесь ключом подписки вручную.
  • Используйте пользовательскую систему, чтобы сделать ключ подписки доступным участникам вашей команды.

Создание подписок и управление ими в портал Azure

Издатели API могут создавать подписки непосредственно на портале Azure.

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

Использование ключа подписки

Подписчик может использовать ключ подписки Управление API одним из двух способов:

  • Добавьте HTTP-заголовок Ocp-Apim-Subscription-Key к запросу, указав значение действительного ключа подписки.

  • Включите параметр запроса subscription-key и правильное значение в URL-адресе. Параметр запроса проверяется только в том случае, если заголовок отсутствует.

Совет

Ocp-Apim-Subscription-Key — это имя заголовка ключа подписки по умолчанию, а ключ подписки — это имя параметра запроса по умолчанию. При необходимости эти имена можно изменить в параметрах для каждого API. Например, на портале обновите эти имена на вкладке "Параметры " API.

Примечание.

Если он включен в заголовок запроса или параметр запроса, ключ подписки по умолчанию передается серверной части и может быть предоставлен в журналах мониторинга серверной части или других системах. Если это считается конфиденциальными данными, можно настроить политику в конце inbound раздела, чтобы удалить заголовок ключа подписки (set-header) или параметр запроса (set-query-parameter).

Включение или отключение требования к подписке для ДОСТУПА к API или продуктам

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

Внимание

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

Примечание.

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

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

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

  • Отключить требование для продукта - на странице Настройки продукта отключите Требуется подписка
  • Отключить требование для API. На странице параметров API отключите необходимую подписку.

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

Сведения о том, как Управление API обрабатывает запросы с ключами подписки или без нее

Запрос API с ключом подписки

Когда Управление API получает запрос API от клиента с ключом подписки, оно обрабатывает запрос в соответствии со следующими правилами:

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

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

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

  2. Если ключ недействителен, но продукт существует, который включает API, но не требует подписки ( открытого продукта), игнорируйте ключ и обрабатывайте запрос API без ключа подписки (см. ниже).

  3. В противном случае доступ будет запрещен (ошибка 401 Отказано в доступе).

Запрос API без ключа подписки

Когда Управление API получает запрос API от клиента без ключа подписки, он обрабатывает запрос в соответствии со следующими правилами:

  1. Сначала проверьте наличие продукта, который включает API, но не требует подписки (открытый продукт). Если открытый продукт существует, обработайте запрос в контексте API, политик и правил доступа, настроенных для открытого продукта. API можно связать не более чем с одним открытым продуктом.
  2. Если открытый продукт, включающий API, не найден, проверьте, требуется ли для API подписка. Если подписка не требуется, обработайте запрос в контексте этого API и операции.
  3. Если настроенный продукт или API не найдены, доступ будет запрещен (ошибка 401 Отказано в доступе).

Сводная таблица

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

Для всех продуктов, назначенных API, требуется подписка ДЛЯ API требуется подписка Вызов API с ключом подписки Вызов API без ключа подписки Типичные сценарии
✔️ ✔️ Разрешен доступ:

• Ключ с областью действия продукта
• Ключ с областью действия API
• Все ключи с областью действия API
• Ключ, ограниченный областью службы

Доступ запрещен:

• Другой ключ не ограничен применимым продуктом или API		 Доступ запрещен Защищенный доступ к API с помощью подписки с областью действия продукта или области действия API
✔️ ❌ Разрешен доступ:

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

• Анонимный доступ к API. Если анонимный доступ не предназначен, настройте политики уровня API для принудительной проверки подлинности и авторизации.
❌ 1 ✔️ Разрешен доступ:

• Ключ с областью действия продукта
• Ключ с областью действия API
• Все ключи с областью действия API
• Ключ с областью действия службы

Доступ запрещен:

• Другой ключ не ограничен применимым продуктом или API		 Разрешен доступ (открытый контекст продукта) • Защищенный доступ к API с подпиской, ограниченной уровнем API

• Анонимный доступ к API. Если анонимный доступ не предназначен, настройте политики продуктов для принудительной проверки подлинности и авторизации
❌ 1 ❌ Разрешен доступ:

• Ключ с областью действия продукта
• Ключ доступа с областью действия API
• Все ключи, ограниченные областью API
• Ключ с областью действия службы
• Другой ключ не ограничен применимым продуктом или API		 Разрешен доступ (открытый контекст продукта) Анонимный доступ к API. Если анонимный доступ не предназначен, настройте политики продуктов для принудительной проверки подлинности и авторизации

1 Открытый продукт существует, связанный с API.

Рекомендации

  • Доступ к API в контексте продукта совпадает с тем, публикуется ли продукт. Отмена публикации продукта скрывает его с портала разработчика, но не делает недействительными новые или существующие ключи подписки.
  • Если API не требует проверки подлинности подписки, любой запрос API, включающий ключ подписки, обрабатывается так же, как запрос без ключа подписки. Ключ подписки игнорируется.
  • Доступ к API в "контексте" означает политики и контроль доступа, применяемые в определенной области (например, API или продукт).

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

Дополнительные сведения о службе управления API:

  • Узнайте, как политики Управления API применяются в разных областях.
  • Узнайте другие понятия в Управлении API.
  • Ознакомьтесь с руководствами по использованию службы управления API.
  • Проверьте нашу страницу Часто задаваемые вопросы для получения информации по распространённым вопросам.