Защита API с помощью проверки подлинности сертификата клиента в службе управления API

ПРИМЕНЯЕТСЯ КО ВСЕМ уровням управления API

Управление API предоставляет возможность защитить доступ к API (то есть клиент к Управлению API) с помощью клиентских сертификатов и взаимной аутентификации TLS. Можно проверить сертификаты, предоставленные подключающимся клиентом, и оценить соответствие свойств сертификата требуемым значениям с помощью выражений политики.

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

Общие сведения о авторизации API см. в разделе "Проверка подлинности и авторизация".

Варианты использования сертификата

Для проверки сертификатов служба управления API может сопоставлять их с сертификатами, управляемыми в вашем экземпляре службы управления API. Если вы решили использовать Управление API для управления сертификатами клиентов, доступны следующие варианты:

• ссылка на сертификат, управляемый в Azure Key Vault;
• добавление файла сертификата непосредственно в Управление API.

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

• сертификаты, хранящиеся в хранилищах ключей, можно многократно использовать в разных службах;
• Политики детального доступа можно применять к сертификатам, хранящимся в хранилищах ключей.
• Обновленные в хранилище ключей сертификаты автоматически поворачиваются в системе управления API. После обновления сертификата в хранилище ключей он обновится в Управлении API в течение 4 часов. Вы также можете вручную обновить сертификат с помощью портала Azure или с помощью REST API управления.

Предпосылки

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

• Вам нужен доступ к сертификату и паролю управления, чтобы управлять им в хранилище ключей Azure или отправить в службу "Управление API". Сертификат должен быть в формате CER или PFX. Разрешено использовать самозаверяющие сертификаты.

  При использовании самозаверяющего сертификата также установите доверенные корневые и промежуточные сертификаты ЦС в экземпляре управления API.

  Замечание

  Сертификаты ЦС для проверки сертификатов не поддерживаются на уровне тарифного плана "Потребление".

Предварительные требования для интеграции с хранилищем ключей

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

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

Настройка доступа к хранилищу ключей

1. На портале Azure перейдите в хранилище ключей.
2. В меню слева выберите Параметры>Конфигурация доступа. Запишите настроенную модель разрешений.
3. В зависимости от модели разрешений настройте либо политику доступа к хранилищу ключей, либо доступ Azure RBAC для управляемого удостоверения в API Management.

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

1. В меню слева выберите политики доступа.
2. На странице политик доступа нажмите кнопку +Создать.
3. На вкладке "Разрешения" в разделе "Разрешения секрета" выберите "Получить" и "Список" и нажмите кнопку "Далее".
4. На вкладке "Основной" найдите управляемое имя ресурса удостоверения, затем выберите "Далее". Если вы используете назначаемое системой удостоверение, субъектом является имя экземпляра Управления API.
5. Снова выберите Далее. На вкладке Проверить и создать выберите Создать.

Сведения о создании сертификата в хранилище ключей или импорте сертификата в хранилище ключей см. в кратком руководстве по настройке и извлечению сертификата из Azure Key Vault с помощью портала Azure.

Требования к брандмауэру хранилища ключей

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

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

• В брандмауэре Key Vault включите опцию Разрешить доверенным службам Microsoft обход этого брандмауэра:

  1. В хранилище ключей выберите Параметры>сеть.
  2. В разделе "Брандмауэры и виртуальные сети" выберите "Разрешить общедоступный доступ" из определенных виртуальных сетей и IP-адресов.
  3. В разделе "Исключение" выберите разрешить доверенным службам Майкрософт обойти этот брандмауэр.

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

• Убедитесь, что локальный IP-адрес клиента временно может получить доступ к хранилищу ключей. Для добавления в службу управления API Azure необходимо выбрать сертификат или секрет. Дополнительные сведения см. в разделе Настройка сетевых параметров Azure Key Vault.

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

Требования к виртуальной сети

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

• Включите конечную точку службы в подсети управления API для Key Vault.
• Настройте правило группы безопасности сети (NSG), чтобы разрешить исходящий трафик к AzureKeyVault и AzureActiveDirectoryтегам служб.

Дополнительные сведения см. в разделе "Конфигурация сети" при настройке управления API в виртуальной сети.

Добавление сертификата, размещенного в хранилище ключей

См. Предварительные требования для интеграции хранилища ключей.

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

1. На портале Azure откройте экземпляр API Management.

2. В разделе Безопасность выберите Сертификаты.

3. Выберите сертификаты, а затем + Добавить.

4. В поле "Идентификатор" введите имя.

5. В разделе Сертификатвыберите Хранилище ключей.

6. Введите идентификатор сертификата, размещенного в хранилище ключей, или щелкните Выбрать, чтобы выбрать сертификат из хранилища ключей.

   Это важно

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

7. В удостоверении клиента выберите назначаемое системой удостоверение или существующее управляемое удостоверение, назначаемое пользователем. Дополнительную информацию см. в статье "Использование управляемых удостоверений в Azure API Management".

   Замечание

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

8. Нажмите кнопку "Добавить".

   

9. Нажмите кнопку "Сохранить".

Загрузить сертификат

Чтобы передать сертификат клиента в Управление API, выполните следующие действия.

1. На портале Azure откройте экземпляр API Management.

2. В разделе Безопасность выберите Сертификаты.

3. Выберите сертификаты, а затем + Добавить.

4. В поле "Идентификатор" введите имя.

5. В списке Сертификат выберите Пользовательский.

6. Найдите PFX-файл сертификата, выберите его и введите соответствующий пароль.

7. Нажмите кнопку "Добавить".

   

8. Нажмите кнопку "Сохранить".

Включение экземпляра управления API для получения и проверки сертификатов клиента

Уровень "Разработчик", "Базовый", "Стандартный" или "Премиум"

Чтобы получать и проверять клиентские сертификаты по протоколу HTTP/2 на уровнях "Разработчик", "Базовый", "Стандартный" или "Премиум", необходимо включить Согласование клиентского сертификата.

1. Выберите "Развертывание и инфраструктура", а затем "Пользовательские домены".

2. Выберите имя узла шлюза.

3. На странице шлюза выберите "Согласование сертификата клиента", а затем "Обновить".

   

Использование, уровень "Базовый" версии 2, "Стандартный" версии 2 или "Премиум" версии 2

Чтобы получить и проверить сертификаты клиента на уровне "Потребление", "Базовый" версии 2, "Стандартный" или "Премиум" версии 2, необходимо включить сертификат клиента запроса.

1. Выберите "Развертывание и инфраструктура", а затем "Пользовательские домены".

2. В разделе Сертификаты клиента включите Запросить сертификат клиента.

   

Политика проверки сертификатов клиента

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

Настройте политику для проверки одного или нескольких атрибутов, включая издателя сертификатов, тему, отпечаток, проверку сертификата на основе списка отзыва через Интернет и другие.

Проверка сертификата с помощью переменных контекста

Вы также можете создавать выражения политики с переменнойcontext для проверки сертификатов клиента. В примерах в следующих разделах показаны выражения, использующие context.Request.Certificate свойство и другие context свойства.

Проверка эмитента и субъекта

Следующие политики можно настроить для проверки издателя и субъекта сертификата клиента:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Issuer != "trusted-issuer" || context.Request.Certificate.SubjectName.Name != "expected-subject-name")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Проверка отпечатка большого пальца

Для проверки отпечатка сертификата клиента можно настроить следующие политики:

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify() || context.Request.Certificate.Thumbprint != "DESIRED-THUMBPRINT-IN-UPPER-CASE")" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

Проверка отпечатка пальца с сертификатами, загруженными в Управление API

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

<choose>
    <when condition="@(context.Request.Certificate == null || !context.Request.Certificate.Verify()  || !context.Deployment.Certificates.Any(c => c.Value.Thumbprint == context.Request.Certificate.Thumbprint))" >
        <return-response>
            <set-status code="403" reason="Invalid client certificate" />
        </return-response>
    </when>
</choose>

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

• Безопасные серверные службы в службе "Управление API Azure"
• Как добавить пользовательский сертификат ЦС в службу управления API Azure
• Политики в службе "Управление API Azure"