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

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управления API

В этой статье показано, как создать управляемую идентификацию для экземпляра Azure API Management и как использовать её для доступа к другим ресурсам. Используя управляемое удостоверение, созданное идентификатором Microsoft Entra, управление API может легко и безопасно получить доступ к другим ресурсам, защищенным Microsoft Entra, например Azure Key Vault. Azure управляет этими удостоверениями, поэтому вам не нужно подготавливать или менять секреты. Дополнительные сведения об управляемых удостоверениях см. в статье "Что такое управляемые удостоверения для ресурсов Azure"?

Инстанции API Management можно предоставить два типа удостоверений.

• Порождаемая системой идентификация связана с вашей службой и удаляется вместе с её удалением. Служба может иметь только одно назначенное системой удостоверение.
• Назначаемый пользователем идентификатор — это автономный ресурс Azure, который можно назначить службе. Служба может иметь несколько назначаемых пользователем идентичностей.

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

Портал Azure

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

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

1. Создайте экземпляр управления API на портале как обычно. Перейдите к нему на портале.

2. В левом меню в разделе Безопасность выберите Управляемые удостоверения.

3. На вкладке "Назначаемая системой" измените Состояние на "Вкл". Выберите Сохранить.

   

Azure PowerShell

В следующих шагах описывается процесс создания экземпляра управления API и назначения ему идентификации с помощью Azure PowerShell.

1. Если вам нужно, установите Azure PowerShell, следуя инструкциям в руководстве по Azure PowerShell. Затем выполните Connect-AzAccount, чтобы создать подключение к Azure.

2. Используйте следующий код для создания экземпляра с системно назначаемым управляемым удостоверением. Дополнительные примеры использования 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 ID основной объект службы имеет то же имя, которое вы дали данному экземпляру службы управления API.

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

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

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

1. На портале Azure перейдите в хранилище ключей.
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.

• В брандмауэре Key Vault включите опцию Разрешить доверенным службам Microsoft обход этого брандмауэра:

  1. В хранилище ключей выберите Параметры>сеть.
  2. В разделе "Брандмауэры и виртуальные сети" выберите "Разрешить общедоступный доступ" из определенных виртуальных сетей и IP-адресов.
  3. В разделе "Исключение" выберите разрешить доверенным службам Майкрософт обойти этот брандмауэр.

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

• Убедитесь, что локальный IP-адрес клиента временно может получить доступ к хранилищу ключей. Для добавления в службу управления API Azure необходимо выбрать сертификат или секрет. Дополнительные сведения см. в разделе Настройка сетевых параметров 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, содержащую секрет.

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

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

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

Шаблон содержит следующие действия.

1. Обновите политики доступа экземпляра Key Vault и разрешите экземпляру API Management получить секреты из него.
2. Обновление экземпляра службы "Управление 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".

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

Портал Azure

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

1. Перейдите к экземпляру службы "Управление API" на портале.

2. В левом меню в разделе Безопасность выберите Управляемые удостоверения.

3. На вкладке User assigned (Назначено пользователем) нажмите Добавить.

4. Найдите созданный ранее идентификатор и выберите его. Выберите Добавить.

   

Azure PowerShell

В следующих шагах описывается процесс создания экземпляра управления API и назначения ему идентификации с помощью Azure PowerShell.

1. Если вам нужно, установите Azure PowerShell, следуя инструкциям в руководстве по Azure PowerShell. Затем выполните Connect-AzAccount, чтобы создать подключение к Azure.

2. Для создания экземпляра используйте следующий код. Дополнительные примеры использования 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 Azure.

Получение пользовательского СЕРТИФИКАТА TLS/SSL для экземпляра службы управления API из Key Vault

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

Рассмотрите следующие требования:

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

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

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

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

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

Регистрация событий в концентратор событий

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

Удаление идентификатора

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

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

Чтобы удалить все идентификаторы с помощью шаблона ARM, обновите следующий раздел:

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

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

• Что такое управляемые удостоверения для ресурсов Azure?
• Шаблоны диспетчера ресурсов Azure
• Аутентифицировать с помощью управляемой идентичности в рамках политики