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

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

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

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

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

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

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

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

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

Предварительные требования

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

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

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

    Примечание

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

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

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

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

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

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

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

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

  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 экземпляра для получения и проверки сертификатов клиента

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

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

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

Уровень "Потребление"

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

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

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

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

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

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

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

Важно!

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

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

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

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

Совет

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

Дальнейшие действия