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

Статья
03/31/2023

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление 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 Management и назначению ему удостоверения с помощью Azure PowerShell.

При необходимости установите Azure PowerShell с помощью инструкций, приведенных в руководстве по Azure PowerShell. Затем выполните Connect-AzAccount, чтобы создать подключение к Azure.
Используйте следующий код для создания экземпляра с управляемым удостоверением, назначаемым системой. Дополнительные примеры использования Azure PowerShell с экземпляром API Management см. в разделе Примеры PowerShell для API Management.
```
# 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

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

"identity" : {
    "type" : "SystemAssigned"
}

Это свойство указывает платформе Azure, что требуется создать удостоверение для экземпляра службы управления API и управлять им.

Например, полный шаблон Azure Resource Manager может выглядеть так:

{
    "$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 Management может оба удостоверения, назначаемое системой и назначаемое пользователем, одновременно. В этом случае свойство type будет иметь значение SystemAssigned,UserAssigned.

Настройка доступа к Key Vault с помощью управляемого удостоверения

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

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

На портале перейдите к хранилищу ключей.
В меню слева выберите конфигурацию Access и запишите настроенную модель разрешений.
В зависимости от модели разрешений настройте политику доступа к хранилищу ключей или доступ 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 в виртуальной сети.

Поддерживаемые сценарии использования удостоверения, назначаемого системой

Получение пользовательского сертификата TLS/SSL для экземпляра API Management из Azure Key Vault

Вы можете использовать назначаемое системой удостоверение экземпляра API Management для получения пользовательских сертификатов TLS/SSL, хранящихся в Azure Key Vault. Затем эти сертификаты можно назначить личным доменам в экземпляре API Management. Имейте в виду следующее:

Тип содержимого секрета должен быть application/x-pkcs12. Узнайте больше о требованиях личного домена к сертификату.
Используйте конечную точку секрета сертификата Key Vault, которая содержит секрет.

Внимание

Если вы не предоставили версию объекта сертификата, API Management автоматически получит самую последнюю версию сертификата в течение четырех часов после ее обновления в Key Vault.

В следующем примере показан шаблон Azure Resource Manager, использующий назначаемое системой управляемое удостоверение экземпляра службы "Управление API" для получения сертификата личного домена из Key Vault.

Необходимые компоненты

Экземпляр службы "Управление API", настроенный с управляемым удостоверением, назначаемым системой. Для создания экземпляра можно использовать шаблон быстрого запуска Azure.
Экземпляр Azure Key Vault в той же группе ресурсов, в которой размещается сертификат, который будет использоваться в качестве сертификата личного домена в Управление API.

Приведенный ниже шаблон содержит следующие шаги:

Обновление политик доступа экземпляра Azure Key Vault и разрешение экземпляру службы "Управление API" получать секреты из экземпляра Azure Key Vault.
Обновление экземпляра службы "Управление 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 service"
            }
        },
		"publisherEmail": {
			"type": "string",
			"minLength": 1,
			"metadata": {
				"description": "The email address of the owner of the service"
			}
		},
		"publisherName": {
			"type": "string",
			"minLength": 1,
			"metadata": {
				"description": "The name of the owner of the service"
			}
		},
		"sku": {
			"type": "string",
			"allowedValues": ["Developer",
			"Standard",
			"Premium"],
			"defaultValue": "Developer",
			"metadata": {
				"description": "The pricing tier of this API Management service"
			}
		},
		"skuCount": {
			"type": "int",
			"defaultValue": 1,
			"metadata": {
				"description": "The instance size of this API Management service."
			}
		},
        "keyVaultName": {
            "type": "string",
            "metadata": {
                "description": "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"
					}
				}]
		}
		}
	}
]
}

Хранение именованных значений из Azure Key Vault и управление ими

Управляемое удостоверение, назначаемое системой, можно использовать для доступа к Azure Key Vault для хранения секретов и управления ими для использования в политиках службы Управления API. Дополнительные сведения см. в статье Использование именованных значений в политиках Управления API Azure.

Проверка подлинности в серверной части с помощью удостоверения службы "Управление API"

Вы можете использовать назначенное системой удостоверение для проверки подлинности в серверной службе с помощью политики authentication-managed-identity.

Подключение к ресурсам Azure за брандмауэром для IP-адресов с помощью управляемого удостоверения, назначаемого системой

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

Служба Azure	Установить связь
Azure Key Vault	Trusted-access-to-azure-key-vault
Хранилище Azure	Trusted-access-to-azure-storage
Служебная шина Azure	Trusted-access-to-azure-service-bus
Центры событий Azure	Trusted-access-to-azure-event-hub

Ведение журнала событий в концентратор событий

Вы можете настроить и использовать управляемое удостоверение, назначаемое системой, для доступа к концентратору событий для ведения журнала событий из экземпляра Управление API. Дополнительные сведения см. в статье "Как регистрировать события для Центры событий Azure в Azure Управление API".

Создание управляемого удостоверения, назначаемого пользователем

Примечание.

Вы можете привязать к экземпляру API Management до 10 управляемых удостоверений, назначаемых пользователем.

Портал Azure

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

Создайте экземпляр управления API на портале как обычно. Перейдите к нему на портале.
В левом меню в разделе Безопасность выберите Управляемые удостоверения.
На вкладке User assigned (Назначаемое пользователем) нажмите Добавить.
Найдите созданное ранее удостоверение и выберите его. Выберите Добавить.

Azure PowerShell

Примечание.

Ниже описаны действия по созданию экземпляра API Management и назначению ему удостоверения с помощью Azure PowerShell.

При необходимости установите Azure PowerShell с помощью инструкций, приведенных в руководстве по Azure PowerShell. Затем выполните Connect-AzAccount, чтобы создать подключение к Azure.

Для создания экземпляра используйте следующий код. Дополнительные примеры использования Azure PowerShell с экземпляром API Management см. в разделе Примеры PowerShell для API Management.

# Create a resource group.
New-AzResourceGroup -Name $resourceGroupName -Location $location

# Create a user-assigned identity. This 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 requires installation of the "Az.ManagedServiceIdentity" module.
$userAssignedIdentity = New-AzUserAssignedIdentity -Name $userAssignedIdentityName -ResourceGroupName $resourceGroupName

# Update an API Management instance
$userIdentities = @($userAssignedIdentity.Id)
Set-AzApiManagement -InputObject $apimService -UserAssignedIdentity $userIdentities

Шаблон Azure Resource Manager

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

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {}
    }
}

При добавлении назначаемого пользователем типа служба Azure будет использовать назначаемое пользователем удостоверение, указанное для вашего экземпляра.

Например, полный шаблон Azure Resource Manager может выглядеть так:

{
    "$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 — это уникальный идентификатор нового удостоверения приложения, с помощью которого можно указать, какое удостоверение следует использовать во время вызовов среды выполнения.

Примечание.

Поддерживаемые сценарии использования управляемого удостоверения, назначаемого пользователем

Получение пользовательского сертификата TLS/SSL для экземпляра API Management из Azure Key Vault

Вы можете использовать назначаемое пользователем удостоверение для установления отношений доверия между экземпляром службы управления API и Azure Key Vault. Это отношение доверия можно использовать для получения настраиваемых сертификатов TLS/SSL, хранящихся в Azure Key Vault. Затем эти сертификаты можно назначить личным доменам в экземпляре API Management.

Внимание

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

Имейте в виду следующее:

Тип содержимого секрета должен быть application/x-pkcs12.
Используйте конечную точку секрета сертификата Key Vault, которая содержит секрет.

Внимание

Полный шаблон см. в разделе Управление API с SSL на основе Key Vault с использованием удостоверения, назначаемого пользователем.

В этом шаблоне будут развернуты перечисленные ниже компоненты.

Экземпляр службы управления API Azure
Управляемое удостоверение, назначаемое пользователем Azure
Azure Key Vault для хранения сертификата SSL/TLS

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

Хранение именованных значений из Azure Key Vault и управление ими

Управляемое удостоверение, назначаемое пользователем, можно использовать для доступа к Azure Key Vault для хранения секретов и управления ими для использования в политиках службы Управления API. Дополнительные сведения см. в статье Использование именованных значений в политиках Управления API Azure.

Примечание.

Проверка подлинности в серверной части с помощью назначаемого пользователем удостоверения

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

Ведение журнала событий в концентратор событий

Вы можете настроить и использовать управляемое удостоверение, назначаемое пользователем, для доступа к концентратору событий для ведения журнала событий из экземпляра Управление API. Дополнительные сведения см. в статье "Как регистрировать события для Центры событий Azure в Azure Управление API".

Удаление удостоверения

Вы можете удалить назначаемое системой удостоверение, отключив эту функцию на портале или с помощью шаблона Azure Resource Manager так же, как при его создании. Назначаемые пользователем удостоверения можно удалить по отдельности. Чтобы удалить все удостоверения, задайте для типа удостоверения значение "None".

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

Чтобы удалить все удостоверения с помощью шаблона Azure Resource Manager, обновите этот раздел:

"identity": {
    "type": "None"
}

Внимание

Если экземпляр API Management настроен с использованием пользовательского SSL-сертификата из Key Vault и вы пытаетесь отключить управляемое удостоверение, запрос завершится ошибкой.

Вы можете выполнить разблокировку самостоятельно, переключившись с сертификата Azure Key Vault на встроенный зашифрованный сертификат, а затем отключив управляемое удостоверение. Дополнительные сведения см. в разделе "Настройка имени личного домена".

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

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

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

Создание управляемого удостоверения, назначаемого системой

Портал Azure

Azure PowerShell

Шаблон Azure Resource Manager

Настройка доступа к Key Vault с помощью управляемого удостоверения

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

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

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

Поддерживаемые сценарии использования удостоверения, назначаемого системой

Получение пользовательского сертификата TLS/SSL для экземпляра API Management из Azure Key Vault

Необходимые компоненты

Хранение именованных значений из Azure Key Vault и управление ими

Проверка подлинности в серверной части с помощью удостоверения службы "Управление API"

Подключение к ресурсам Azure за брандмауэром для IP-адресов с помощью управляемого удостоверения, назначаемого системой

Ведение журнала событий в концентратор событий

Создание управляемого удостоверения, назначаемого пользователем

Портал Azure

Azure PowerShell

Шаблон Azure Resource Manager

Поддерживаемые сценарии использования управляемого удостоверения, назначаемого пользователем

Получение пользовательского сертификата TLS/SSL для экземпляра API Management из Azure Key Vault

Хранение именованных значений из Azure Key Vault и управление ими

Проверка подлинности в серверной части с помощью назначаемого пользователем удостоверения

Ведение журнала событий в концентратор событий

Удаление удостоверения

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

Дополнительные ресурсы