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

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление 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.

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

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

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

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

  2. В меню слева выберите конфигурацию Access и запишите настроенную модель разрешений.

  3. В зависимости от модели разрешений настройте политику доступа к хранилищу ключей или доступ Azure RBAC для управляемого удостоверения Управление API.

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

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

    Чтобы настроить доступ к Azure RBAC, выполните приведенные действия.

    1. В меню слева выберите Управление доступом (IAM).
    2. На странице управления доступом (IAM) выберите " Добавить назначение роли".
    3. На вкладке "Роль" выберите "Пользователь сертификата Key Vault".
    4. На вкладке "Члены" выберите "Управляемое удостоверение>" и "Выбрать участников".
    5. На странице "Выбор управляемого удостоверения" выберите управляемое удостоверение, назначаемое системой, или назначаемое пользователем управляемое удостоверение, связанное с экземпляром Управление API, а затем нажмите кнопку "Выбрать".
    6. Выберите Проверить + назначить.

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

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

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

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

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

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

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

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

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

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

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

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

Внимание

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

Внимание

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

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

  1. Перейдите к экземпляру Управления API на портале Azure.

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

  3. Щелкните Сертификаты>Добавить.

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

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

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

    Внимание

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

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

    Примечание.

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

  8. Выберите Добавить.

    Снимок экрана: добавление сертификата хранилища ключей для Управление API на портале.

  9. Выберите Сохранить.

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

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

  1. Перейдите к экземпляру Управления API на портале Azure.

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

  3. Щелкните Сертификаты>Добавить.

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

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

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

  7. Выберите Добавить.

    Снимок экрана: отправка сертификата клиента в Управление API на портале.

  8. Выберите Сохранить.

Примечание.

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

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

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

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

Согласование сертификата клиента

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

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

Запросить сертификат клиента

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

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

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

Проверка сертификата с использованием переменных context

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

Примечание.

Взаимная проверка подлинности сертификатов может не работать правильно, если конечная точка шлюза Управление API предоставляется через Шлюз приложений. Это связано с тем, что Шлюз приложений функции в качестве подсистемы балансировки нагрузки уровня 7, устанавливая отдельное SSL-соединение с серверной службой Управление API. Следовательно, сертификат, подключенный клиентом в исходном HTTP-запросе, не будет перенаправляться в APIM. Однако в качестве обходного решения можно передать сертификат с помощью параметра переменных сервера. Подробные инструкции см. в разделе "Переменные сервера взаимной проверки подлинности".

Внимание

  • Начиная с мая 2021 г. свойство context.Request.Certificate запрашивает сертификат только в том случае, если hostnameConfiguration экземпляра Управления API устанавливает для свойства negotiateClientCertificate значение True. По умолчанию negotiateClientCertificate имеет значение False.
  • Если в клиенте отключено повторное согласование TLS, при запросе сертификата с помощью свойства context.Request.Certificate могут возникнуть ошибки TLS. Если это происходит, включите параметры повторного согласования TLS в клиенте.
  • Повторное согласование сертификации не поддерживается на уровнях Управление API версии 2.

Проверка издателя и субъекта

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

<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>

Примечание.

Чтобы отключить список отзыва сертификатов, используйте context.Request.Certificate.VerifyNoRevocation() вместо context.Request.Certificate.Verify()него. Если сертификат клиента является самозаверяющим, то для работы context.Request.Certificate.Verify() и context.Request.Certificate.VerifyNoRevocation() сертификаты корневого (или промежуточного) ЦС необходимо отправить в Управление API.

Проверка отпечатка

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

<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>

Примечание.

Чтобы отключить список отзыва сертификатов, используйте context.Request.Certificate.VerifyNoRevocation() вместо context.Request.Certificate.Verify()него. Если сертификат клиента является самозаверяющим, то для работы context.Request.Certificate.Verify() и context.Request.Certificate.VerifyNoRevocation() сертификаты корневого (или промежуточного) ЦС необходимо отправить в Управление API.

Проверка отпечатка на соответствие сертификатам, переданным в службу управления 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>

Примечание.

Чтобы отключить список отзыва сертификатов, используйте context.Request.Certificate.VerifyNoRevocation() вместо context.Request.Certificate.Verify()него. Если сертификат клиента является самозаверяющим, то для работы context.Request.Certificate.Verify() и context.Request.Certificate.VerifyNoRevocation() сертификаты корневого (или промежуточного) ЦС необходимо отправить в Управление API.

Совет

Проблема взаимоблокировки сертификатов клиента, описанная в этой статье, может проявиться несколькими разными способами, например, когда запросы прекращают выполняться или выдают код состояния 403 Forbidden после истечения времени ожидания, context.Request.Certificate имеет значение null. Эта проблема обычно влияет на запросы POST и PUT с длиной содержимого около 60 КБ или более. Чтобы предотвратить возникновение этой проблемы, включите параметр "Согласование сертификата клиента" для нужных имен узлов в колонке "Личные домены", как показано на первом рисунке в этом документе. Эта функция недоступна на уровне "Потребление".

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