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

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

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

Примечание.

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

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

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

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

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

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

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

Совет

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

• OAuth2.0 (дополнительные сведения см. здесь);
• сертификаты клиентов (см. эту статью);
• Ограничение IP-адресов вызывающих объектов

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

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

Задание определенных ключей вместо повторного создания можно выполнить путем вызова подписки Azure Управление API — создания или обновления REST API Azure. В частности, 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 поставляется со встроенной подпиской на все доступы, которая предоставляет доступ ко всем API. Эта подписка на уровне службы упрощает тестирование и отладку API-интерфейсов владельцев служб в тестовой консоли.

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

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

Примечание.

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

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

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

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

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

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

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

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

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

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

• Добавьте в запрос заголовок Ocp-Apim-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. Если анонимный доступ не предназначен, настройте политики продуктов для принудительной проверки подлинности и авторизации

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

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

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

Следующие шаги

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

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