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

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

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

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

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

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

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

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

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

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

Предпосылки

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

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

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

  Замечание

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

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

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

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

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

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

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

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

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

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

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

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

• В брандмауэре хранилища ключей установите флажок Разрешить доверенным службам Майкрософт обходить этот брандмауэр.

• Убедитесь, что IP-адрес локального клиента временно может получить доступ к хранилищу ключей при выборе сертификата или секрета для добавления в Azure API Management. Дополнительные сведения см. в разделе Настройка сетевых параметров 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 на уровнях "Разработчик", "Базовый", "Стандартный" или "Премиум", необходимо включить настройку "Согласование клиентского сертификата" на панели "Пользовательский домен", как показано ниже.

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

Чтобы получать и проверять клиентские сертификаты в уровнях Consumption, Basic v2, Standard v2 или Premium v2, необходимо включить настройку Запрос сертификата клиента на панели Пользовательские домены, как показано ниже.

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

Используйте политику проверки сертификата клиента для проверки одного или нескольких атрибутов сертификата клиента, используемого для доступа к 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.