Использование именованных значений в политиках управления API Azure

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

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

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

Типы значений

Обычные значения или секреты могут содержать выражения политики. Например, выражение @(DateTime.Now.ToString()) возвращает строку, содержащую текущую дату и время.

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

Секреты хранилища ключей

Значения секретов можно хранить как зашифрованные строки в службе управления API (пользовательские секреты) или ссылаться на секреты в Azure Key Vault.

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

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

Предпосылки

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Добавление или изменение именованного значения

Добавление секрета хранилища ключей в управление API

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

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

2. В разделе API выберите "Именованные значения>" и "Добавить".

3. Введите идентификатор имени и введите отображаемое имя , используемое для ссылки на свойство в политиках.

4. Добавьте один или несколько необязательных тегов , чтобы упорядочить именованные значения.

5. В раскрывающемся списке "Тип" выберите хранилище ключей.

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

   Это важно

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

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

   Замечание

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

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

   

Добавление обычного или секретного значения в управление API

az apim nv create --resource-group apim-hello-word-resource-group \
    --display-name "named_value_01" --named-value-id named_value_01 \
    --secret true --service-name apim-hello-world --value test

az apim nv list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table

az apim nv show --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

az apim nv show-secret --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

az apim nv delete --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --named-value-id named_value_01

Использование именованного значения

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

Чтобы использовать именованное значение в политике, поместите отображаемое имя в двойную пару фигурных скобок, как {{ContosoHeader}}показано в следующем примере:

<set-header name="{{ContosoHeader}}" exists-action="override">
  <value>{{ContosoHeaderValue}}</value>
</set-header>

В этом примере ContosoHeader используется в качестве имени заголовка в set-header политике и ContosoHeaderValue используется в качестве значения этого заголовка. Если эта политика вычисляется во время запроса или ответа на шлюз управления API, {{ContosoHeader}} а {{ContosoHeaderValue}} затем заменяются соответствующими значениями.

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

<set-header name = "CustomHeader{{ContosoHeader}}" ...>

Именованные значения также могут содержать выражения политики. В следующем примере используется выражение ExpressionProperty.

<set-header name="CustomHeader" exists-action="override">
    <value>{{ExpressionProperty}}</value>
</set-header>

При оценке этой политики {{ExpressionProperty}} заменяется на @(DateTime.Now.ToString()). Поскольку значение является выражением политики, это выражение обрабатывается, и политика продолжает выполняться.

Это можно проверить на портале Azure или на портале разработчика, с помощью вызова операции с политикой, использующей именованные значения в пределах области. В следующем примере операция вызывается с двумя предыдущими примерами set-header политик с именованными значениями. Обратите внимание, что ответ содержит два настраиваемых заголовка, которые были настроены с помощью политик с именованными значениями.

При просмотре трассировки исходящего API для вызова, содержащего два предыдущих примера политик с именованными значениями, можно увидеть две set-header политики с именованными значениями, вставленными, а также оценку выражения политики для именованного значения, в котором содержалось выражение политики.

Можно также использовать интерполяцию строк с именованными значениями.

<set-header name="CustomHeader" exists-action="override">
    <value>@($"The URL encoded value is {System.Net.WebUtility.UrlEncode("{{ContosoHeaderValue2}}")}")</value>
</set-header>

Значение CustomHeader для этого параметра будет The URL encoded value is This+is+a+header+value..

Хотя именованные значения могут содержать выражения политики, они не могут содержать другие именованные значения. Если текст, содержащий именованную ссылку на значение, используется для значения, например Text: {{MyProperty}}, эта ссылка не будет обработана и заменена.

Удаление именованного значения

Чтобы удалить именованное значение, выберите имя, а затем выберите "Удалить " в контекстном меню (...).

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

Дополнительные сведения о работе с политиками:

• Политики в управлении API
• Справочник по политикам
• Выражения политики