Примечание
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API
В этой статье показано, как создать управляемую идентификацию для экземпляра Azure API Management и как использовать её для доступа к другим ресурсам. Управляемое удостоверение, созданное идентификатором Microsoft Entra, позволяет управлению API легко и безопасно получать доступ к другим ресурсам, защищенным Microsoft Entra, например Azure Key Vault. Azure управляет этими удостоверениями, поэтому вам не нужно подготавливать или менять секреты. Сведения об управляемых удостоверениях см. в статье Что такое управляемые удостоверения для ресурсов Azure?.
Экземпляру API Management можно предоставить два типа удостоверений.
- Назначаемое системой удостоверение привязывается к службе и удаляется при удалении этой службы. Служба может иметь только одно назначенное системой удостоверение.
- Назначаемое пользователем удостоверение — это изолированный ресурс Azure, который можно назначить службе. Служба может иметь несколько назначаемых пользователем удостоверений.
Примечание.
Управляемые идентичности являются частью конкретного клиента Microsoft Entra, где размещена ваша подписка Azure. Они не обновляются при перемещении подписки в другой каталог. Если подписка перенесена, необходимо повторно создать и перенастроить учётные записи.
Примечание.
В настоящее время эта функция недоступна в рабочих областях.
Создание управляемого удостоверения, назначаемого системой
Портал Azure
Чтобы настроить управляемое удостоверение в портале Azure, создайте экземпляр API Management, а затем включите эту функцию.
Создайте экземпляр управления API на портале как обычно. Перейдите к нему на портале.
В левом меню в разделе Безопасность выберите Управляемые удостоверения.
На вкладке "Назначаемая системой" измените Состояние на "Вкл". Выберите Сохранить.
Azure PowerShell
Примечание.
Мы рекомендуем использовать модуль Azure Az PowerShell для взаимодействия с Azure. Чтобы начать работу, см. статью Установка Azure PowerShell. Дополнительные сведения см. в статье Перенос Azure PowerShell с AzureRM на Az.
В следующих шагах описывается процесс создания экземпляра управления API и назначения ему идентификации с помощью Azure PowerShell.
Если вам нужно, установите Azure PowerShell, следуя инструкциям в руководстве по Azure PowerShell. Затем выполните
Connect-AzAccount, чтобы создать подключение к Azure.Используйте следующий код для создания экземпляра с системно назначаемым управляемым удостоверением. Дополнительные примеры использования Azure PowerShell с управлением API см. в примерах PowerShell для управления API.
# Create a resource group. New-AzResourceGroup -Name $resourceGroupName -Location $location # Create an API Management Consumption SKU service. New-AzApiManagement -ResourceGroupName $resourceGroupName -Name consumptionskuservice -Location $location -Sku Consumption -Organization contoso -AdminEmail contoso@contoso.com -SystemAssignedIdentity
Можно также обновить существующий экземпляр, чтобы создать удостоверение:
# Get an API Management instance
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName
# Update an API Management instance
Set-AzApiManagement -InputObject $apimService -SystemAssignedIdentity
Шаблон Azure Resource Manager (ARM)
Экземпляр управления API можно создать с система-назначенной идентичностью, включив следующее свойство в определение ресурса в шаблоне ARM:
"identity" : {
"type" : "SystemAssigned"
}
Это свойство предписывает Azure создавать и управлять удостоверением для вашего экземпляра управления API.
Например, полный шаблон ARM может выглядеть следующим образом:
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "0.9.0.0",
"resources": [{
"apiVersion": "2021-08-01",
"name": "contoso",
"type": "Microsoft.ApiManagement/service",
"location": "[resourceGroup().location]",
"tags": {},
"sku": {
"name": "Developer",
"capacity": "1"
},
"properties": {
"publisherEmail": "admin@contoso.com",
"publisherName": "Contoso"
},
"identity": {
"type": "systemAssigned"
}
}]
}
Созданный экземпляр будет иметь следующие дополнительные свойства:
"identity": {
"type": "SystemAssigned",
"tenantId": "<TENANTID>",
"principalId": "<PRINCIPALID>"
}
Свойство tenantId определяет, к какой клиенту Microsoft Entra принадлежит удостоверение. свойство principalId, являющееся уникальным идентификатором нового удостоверения экземпляра. В идентификаторе Microsoft Entra субъект-служба имеет то же имя, которое вы предоставили вашему Управление API экземпляру.
Примечание.
Экземпляр управления API может иметь как назначаемые системой, так и назначаемые пользователем удостоверения. В этом сценарии свойство type — это SystemAssigned,UserAssigned.
Настройка доступа Key Vault с помощью управляемого удостоверения
Для доступа к сертификатам из хранилища ключей Azure с использованием средств управления API требуется настроить следующие конфигурации.
Настройка доступа к хранилищу ключей
- На портале перейдите в хранилище ключей.
- В меню слева выберите конфигурацию Access. Обратите внимание на модель разрешений , настроенную.
- В зависимости от модели разрешений настройте политику доступа к хранилищу ключей или доступ Azure RBAC для управляемого удостоверения Управление API.
Чтобы добавить политику доступа к хранилищу ключей, выполните следующие действия.
- В меню слева выберите политики доступа.
- На странице политик доступа нажмите кнопку +Создать.
- На вкладке "Разрешения" в разделе "Разрешения секрета" выберите "Получить" и "Список" и нажмите кнопку "Далее".
- На вкладке "Субъект" выберите "Субъект", найдите имя ресурса управляемого удостоверения и нажмите кнопку "Далее". Если вы используете назначаемое системой удостоверение, субъектом является имя экземпляра Управления API.
- Снова выберите Далее. На вкладке Проверить и создать выберите Создать.
Чтобы настроить доступ к Azure RBAC, выполните приведенные действия.
- В меню слева выберите Управление доступом (IAM).
- На странице управления доступом (IAM) выберите " Добавить назначение роли".
- На вкладке "Роль" выберите "Пользователь сертификата Key Vault".
- На вкладке "Члены" выберите "Управляемое удостоверение
- В окне "Выбор управляемых удостоверений " выберите управляемое удостоверение, назначаемое системой, или назначаемое пользователем управляемое удостоверение, связанное с экземпляром управления API, и нажмите кнопку "Выбрать".
- Выберите Проверить + назначить.
Требования к брандмауэру хранилища ключей
Если брандмауэр Key Vault включен в хранилище ключей, необходимо выполнить следующие требования:
Для доступа к хранилищу ключей необходимо использовать назначаемое системой управляемое удостоверение экземпляра управления API.
В брандмауэре хранилища ключей установите флажок Разрешить доверенным службам Майкрософт обходить этот брандмауэр.
Убедитесь, что IP-адрес локального клиента временно может получить доступ к хранилищу ключей при выборе сертификата или секрета для добавления в Azure API Management. Дополнительные сведения см. в разделе Настройка сетевых параметров Azure Key Vault.
После завершения настройки можно заблокировать адрес клиента в брандмауэре хранилища ключей.
Требования к виртуальной сети
Если экземпляр службы управления API развернут в виртуальной сети, настройте также следующие параметры сети.
- Включите конечную точку службы в подсети управления API для Key Vault.
- Настройте правило группы безопасности сети (NSG), разрешающее исходящий трафик для тегов службы AzureKeyVault и AzureActiveDirectory.
Дополнительные сведения см. в разделе "Конфигурация сети" при настройке управления API в виртуальной сети.
Поддерживаемые сценарии, использующие назначаемое системой удостоверение
Ниже приведены некоторые распространенные сценарии использования управляемого удостоверения, назначаемого системой, в службе управления API Azure.
Получение пользовательского СЕРТИФИКАТА TLS/SSL для экземпляра службы управления API из Key Vault
Вы можете использовать системное удостоверение экземпляра управления API для получения пользовательских сертификатов TLS/SSL, хранящихся в Key Vault. Затем эти сертификаты можно назначить личным доменам в экземпляре API Management. Учитывайте следующие аспекты:
- Тип содержимого секрета должен быть application/x-pkcs12. Дополнительные сведения см. в разделе "Параметры сертификата домена".
- Необходимо использовать конечную точку секрета сертификата Key Vault, содержащую секрет.
Внимание
Если вы не предоставляете объектную версию сертификата, управление API автоматически получает более новую версию сертификата в течение четырех часов после обновления в Key Vault.
В следующем примере показан шаблон ARM, который использует системно назначенное управляемое удостоверение экземпляра API Management для получения сертификата пользовательского домена из Key Vault.
Необходимые компоненты
- Экземпляр управления API, настроенный с помощью управляемого удостоверения, назначаемого системой. Для создания экземпляра можно использовать шаблон быстрого запуска Azure.
- Экземпляр Key Vault в той же группе ресурсов. Экземпляр должен содержать сертификат, который будет использоваться в качестве сертификата для пользовательского домена в службе управления API.
Шаблон содержит следующие шаги.
- Обновите политики доступа экземпляра Key Vault и разрешите экземпляру API Management получить секреты из него.
- Обновление экземпляра службы "Управление API" путем настройки имени личного домена с использованием сертификата из экземпляра Key Vault.
При запуске шаблона укажите значения параметров, соответствующие вашей среде.
{
"$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {
"apiManagementServiceName": {
"type": "string",
"minLength": 8,
"metadata":{
"description": "The name of the API Management instance"
}
},
"publisherEmail": {
"type": "string",
"minLength": 1,
"metadata": {
"description": "The email address of the owner of the instance"
}
},
"publisherName": {
"type": "string",
"minLength": 1,
"metadata": {
"description": "The name of the owner of the instance"
}
},
"sku": {
"type": "string",
"allowedValues": ["Developer",
"Standard",
"Premium"],
"defaultValue": "Developer",
"metadata": {
"description": "The pricing tier of the API Management instance"
}
},
"skuCount": {
"type": "int",
"defaultValue": 1,
"metadata": {
"description": "The instance size of the API Management instance"
}
},
"keyVaultName": {
"type": "string",
"metadata": {
"description": "The name of the key vault"
}
},
"proxyCustomHostname1": {
"type": "string",
"metadata": {
"description": "Gateway custom hostname 1. Example: api.contoso.com"
}
},
"keyVaultIdToCertificate": {
"type": "string",
"metadata": {
"description": "Reference to the key vault certificate. Example: https://contoso.vault.azure.net/secrets/contosogatewaycertificate"
}
}
},
"variables": {
"apimServiceIdentityResourceId": "[concat(resourceId('Microsoft.ApiManagement/service', parameters('apiManagementServiceName')),'/providers/Microsoft.ManagedIdentity/Identities/default')]"
},
"resources": [
{
"apiVersion": "2021-08-01",
"name": "[parameters('apiManagementServiceName')]",
"type": "Microsoft.ApiManagement/service",
"location": "[resourceGroup().location]",
"tags": {
},
"sku": {
"name": "[parameters('sku')]",
"capacity": "[parameters('skuCount')]"
},
"properties": {
"publisherEmail": "[parameters('publisherEmail')]",
"publisherName": "[parameters('publisherName')]"
},
"identity": {
"type": "systemAssigned"
}
},
{
"type": "Microsoft.KeyVault/vaults/accessPolicies",
"name": "[concat(parameters('keyVaultName'), '/add')]",
"apiVersion": "2018-02-14",
"properties": {
"accessPolicies": [{
"tenantId": "[reference(variables('apimServiceIdentityResourceId'), '2018-11-30').tenantId]",
"objectId": "[reference(variables('apimServiceIdentityResourceId'), '2018-11-30').principalId]",
"permissions": {
"secrets": ["get", "list"]
}
}]
}
},
{
"apiVersion": "2021-04-01",
"type": "Microsoft.Resources/deployments",
"name": "apimWithKeyVault",
"dependsOn": [
"[resourceId('Microsoft.ApiManagement/service', parameters('apiManagementServiceName'))]"
],
"properties": {
"mode": "incremental",
"template": {
"$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"parameters": {},
"resources": [{
"apiVersion": "2021-08-01",
"name": "[parameters('apiManagementServiceName')]",
"type": "Microsoft.ApiManagement/service",
"location": "[resourceGroup().location]",
"tags": {
},
"sku": {
"name": "[parameters('sku')]",
"capacity": "[parameters('skuCount')]"
},
"properties": {
"publisherEmail": "[parameters('publisherEmail')]",
"publisherName": "[parameters('publisherName')]",
"hostnameConfigurations": [{
"type": "Proxy",
"hostName": "[parameters('proxyCustomHostname1')]",
"keyVaultId": "[parameters('keyVaultIdToCertificate')]"
}]
},
"identity": {
"type": "systemAssigned"
}
}]
}
}
}
]
}
Хранение именованных значений из Key Vault и управление ими
Управляемое удостоверение, назначаемое системой, можно использовать для доступа к Key Vault, чтобы хранить и управлять секретами для использования в политиках управления API. Дополнительные сведения см. в статье Использование именованных значений в политиках Управления API Azure.
Проверка подлинности в серверной части с помощью удостоверения службы "Управление API"
Удостоверение, назначаемое системой, можно использовать для проверки подлинности в серверной службе с помощью политики идентификации, управляемой проверкой подлинности .
Подключение к ресурсам Azure за брандмауэром IP с помощью управляемого удостоверения, назначаемого системой
Управление API — это доверенная служба Майкрософт для следующих ресурсов. Это надежное состояние позволяет службе подключаться к следующим ресурсам за брандмауэром. После явного назначения соответствующей роли Azure управляемому удостоверению, назначенному системой для экземпляра ресурса, область доступа для экземпляра соответствует роли Azure, назначенной управляемому удостоверению.
- Надежный доступ для Key Vault
- Надежный доступ для службы хранилища Azure
- Доверенный доступ для служебной шины Azure
- Доверенный доступ для Центров событий Azure
Ведение журнала событий в концентратор событий
Вы можете настроить и использовать управляемое удостоверение, назначенное системой, для доступа к концентратору событий и регистрации активности из экземпляра управления API. Дополнительные сведения см. в разделе "Как регистрировать события в Центры событий" в службе "Управление API Azure".
Создание управляемого удостоверения, назначаемого пользователем
Примечание.
Экземпляр управления API можно связать с 10 управляемыми удостоверениями, назначаемыми пользователем.
Портал Azure
Чтобы настроить управляемое удостоверение на портале, необходимо сначала создать экземпляр API Management и создать пользовательское назначенное удостоверение. Затем выполните следующие шаги.
Перейдите к экземпляру службы "Управление API" на портале.
В левом меню в разделе Безопасность выберите Управляемые удостоверения.
На вкладке User assigned (Назначаемое пользователем) нажмите Добавить.
Найдите созданное ранее удостоверение и выберите его. Выберите Добавить.
Azure PowerShell
Примечание.
Мы рекомендуем использовать модуль Azure Az PowerShell для взаимодействия с Azure. Чтобы начать работу, см. статью Установка Azure PowerShell. Дополнительные сведения см. в статье Перенос Azure PowerShell с AzureRM на Az.
В следующих шагах описывается процесс создания экземпляра управления API и назначения ему идентификации с помощью Azure PowerShell.
Если вам нужно, установите Azure PowerShell, следуя инструкциям в руководстве по Azure PowerShell. Затем выполните
Connect-AzAccount, чтобы создать подключение к Azure.Для создания экземпляра используйте следующий код. Дополнительные примеры использования Azure PowerShell с управлением API см. в примерах PowerShell для управления API.
# Create a resource group. New-AzResourceGroup -Name $resourceGroupName -Location $location # Create a user-assigned identity. This code requires installation of the Az.ManagedServiceIdentity module. $userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName # Create an API Management Consumption SKU service. $userIdentities = @($userAssignedIdentity.Id) New-AzApiManagement -ResourceGroupName $resourceGroupName -Location $location -Name $apiManagementName -Organization contoso -AdminEmail admin@contoso.com -Sku Consumption -UserAssignedIdentity $userIdentities
Можно также обновить существующую службу, чтобы назначить ей удостоверение:
# Get an API Management instance.
$apimService = Get-AzApiManagement -ResourceGroupName $resourceGroupName -Name $apiManagementName
# Create a user-assigned identity. This code requires installation of the Az.ManagedServiceIdentity module.
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName
# Update the API Management instance.
$userIdentities = @($userAssignedIdentity.Id)
Set-AzApiManagement -InputObject $apimService -UserAssignedIdentity $userIdentities
Шаблон ARM
Вы можете создать экземпляр службы Управление API, который имеет идентичность, добавив следующее свойство в определение ресурса:
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"<RESOURCEID>": {}
}
}
Добавление пользовательского назначенного типа сообщает Azure об использовании пользовательского назначенного идентификатора, указанного для вашего экземпляра.
Например, полный шаблон ARM может выглядеть следующим образом:
{
"$schema": "https://schema.management.azure.com/schemas/2014-04-01-preview/deploymentTemplate.json#",
"contentVersion": "0.9.0.0",
"resources": [{
"apiVersion": "2021-08-01",
"name": "contoso",
"type": "Microsoft.ApiManagement/service",
"location": "[resourceGroup().location]",
"tags": {},
"sku": {
"name": "Developer",
"capacity": "1"
},
"properties": {
"publisherEmail": "admin@contoso.com",
"publisherName": "Contoso"
},
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]": {}
}
},
"dependsOn": [
"[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
]
}]
}
Созданная служба будет иметь следующие дополнительные свойства:
"identity": {
"type": "UserAssigned",
"userAssignedIdentities": {
"<RESOURCEID>": {
"principalId": "<PRINCIPALID>",
"clientId": "<CLIENTID>"
}
}
}
Это principalId свойство является уникальным идентификатором для удостоверения, используемого для администрирования Microsoft Entra. свойство clientId — это уникальный идентификатор нового удостоверения приложения, с помощью которого можно указать, какое удостоверение следует использовать во время вызовов среды выполнения.
Примечание.
Экземпляр управления API может иметь как назначаемые системой, так и назначаемые пользователем удостоверения. В этом сценарии свойство type будет SystemAssigned,UserAssigned.
Поддерживаемые сценарии, использующие управляемые удостоверения, назначаемые пользователем
Ниже приведены некоторые распространенные сценарии использования управляемого удостоверения, назначаемого пользователем, в службе управления API Azure.
Получение пользовательского СЕРТИФИКАТА TLS/SSL для экземпляра службы управления API из Key Vault
Вы можете использовать удостоверение, назначенное пользователем, чтобы установить доверие между экземпляром службы управления API и хранилищем ключей. Затем это доверие можно использовать для получения пользовательских TLS/SSL-сертификатов, хранящихся в Key Vault. Затем эти сертификаты можно назначить личным доменам в экземпляре API Management.
Внимание
Если в хранилище ключей включен брандмауэр Key Vault, вы не сможете использовать назначаемое пользователем удостоверение для доступа из службы Управления API. Вместо этого можно использовать удостоверение, назначаемое системой. В брандмауэре Key Vault необходимо включить параметр "Разрешить доверенным службам Майкрософт", чтобы обойти этот параметр брандмауэра .
Учитывайте следующие аспекты:
- Тип содержимого секрета должен быть application/x-pkcs12.
- Необходимо использовать конечную точку секрета сертификата Key Vault, содержащую секрет.
Внимание
Если вы не предоставляете объектную версию сертификата, управление API автоматически получает более новую версию сертификата в течение четырех часов после обновления в Key Vault.
Хранение именованных значений из Key Vault и управление ими
Управляемое удостоверение, назначаемое пользователем, можно использовать для доступа к Key Vault, чтобы хранить и управлять секретами, которые используются в политиках управления API. Дополнительные сведения см. в статье Использование именованных значений в политиках Управления API Azure.
Примечание.
Если в хранилище ключей включен брандмауэр Key Vault, вы не сможете использовать назначаемое пользователем удостоверение для доступа из службы Управления API. Вместо этого можно использовать удостоверение, назначаемое системой. В брандмауэре Key Vault необходимо включить параметр "Разрешить доверенным службам Майкрософт", чтобы обойти этот параметр брандмауэра .
Проверка подлинности в серверной части с помощью назначаемого пользователем удостоверения
Вы можете использовать назначенную пользователем идентичность для аутентификации в серверной службе через политику authentication-managed-identity.
Ведение журнала событий в концентратор событий
Вы можете настроить и использовать пользовательское управляемое удостоверение для доступа к событийному концентратору для логирования событий из экземпляра службы управления API. Дополнительные сведения см. в статье "Как регистрировать события для Центры событий Azure в Azure Управление API".
Удаление удостоверения
Вы можете удалить системно назначенную идентификацию, отключив функцию через портал или шаблон ARM таким же образом, как она была создана. Назначаемые пользователем удостоверения можно удалить по отдельности. Чтобы удалить все удостоверения, задайте для типа удостоверения значение "None".
Удаление идентификатора, назначенного системой, таким образом также удаляет его из Microsoft Entra ID. Удостоверения, назначаемые системой, также автоматически удаляются из идентификатора Microsoft Entra при удалении экземпляра Управление API.
Чтобы удалить все идентификаторы с помощью шаблона ARM, обновите следующий раздел:
"identity": {
"type": "None"
}
Внимание
Если экземпляр управления API настроен с использованием пользовательского SSL-сертификата из Key Vault, и вы пытаетесь отключить управляемое удостоверение, выполнение запроса завершается неудачей.
Это можно устранить, переключив сертификат Key Vault на встроенный сертификат, а затем отключив управляемое удостоверение. Дополнительные сведения см. в разделе "Настройка имени личного домена".