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

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

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

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

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

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

портал Azure

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

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

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

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

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

   

Azure PowerShell

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

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

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

   # 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"
}

Это свойство предписывает создавать и управлять удостоверением для вашего экземпляра управления API в Azure.

Например, полный шаблон 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. В зависимости от модели разрешений настройте политику доступа к хранилищу ключей key vault или доступ Azure RBAC для управляемого удостоверения в API Management.

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

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

Чтобы настроить доступ Azure RBAC:

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

Требования к брандмауэру Key Vault

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Обновите политики доступа экземпляра Key Vault и позвольте экземпляру Управления API получить ключи из него.
2. Обновите экземпляр API Management, задав пользовательское доменное имя с помощью сертификата из экземпляра 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. Дополнительные сведения см. в разделе Использовать именованные значения в политиках Azure API Management.

Аутентификация на серверной стороне с помощью идентификатора 'Управление API'

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

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

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

• доверенный доступ для Key Vault
• Доверенный доступ для служба хранилища Azure
• Доверенный доступ для Служебная шина Azure
• Доверенный доступ для Центры событий Azure

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

Вы можете настроить и использовать управляемое удостоверение, назначенное системой, для доступа к концентратору событий и регистрации активности из экземпляра управления API. Дополнительные сведения см. в статье How to log events to Event Hubs in Azure API Management.

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

портал 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 см. в примерах API Management PowerShell.

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

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

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

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

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

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

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

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

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

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

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

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

Вы можете настроить и использовать пользовательское управляемое удостоверение для доступа к событийному концентратору для логирования событий из экземпляра службы управления API. Дополнительные сведения см. в разделе How to log events to Центры событий Azure in Azure API Management.

Рекомендации по безопасности для управляемых удостоверений

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

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

• Следуйте принципу наименьших привилегий при назначении ролей Azure управляемым удостоверениям. Предоставьте только необходимые разрешения для службы.
• Назначьте только роль участника управления API или разрешения на редактирование политики (например Microsoft.ApiManagement/service/apis/write , и Microsoft.ApiManagement/service/apis/policies/write) доверенным пользователям.
• Регулярно просматривайте и проверяйте назначения ролей управляемых удостоверений и отслеживайте, кто имеет доступ к редактированию политик управления API.
• Реализуйте контрольные меры для политики и управление, чтобы предотвратить несанкционированные изменения критически важных политик.

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

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

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

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

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

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

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