在 Azure API Management 中使用托管标识

适用于：API 管理的所有层级

本文介绍如何为Azure API Management实例创建托管标识，以及如何使用它来access其他资源。 Microsoft Entra ID生成的托管标识使API Management能够轻松安全地access受 Microsoft Entra 保护的其他资源，例如Azure Key Vault。 Azure管理这些标识，因此无需预配或轮换任何机密。有关托管标识的详细信息，请参阅什么是Azure资源的托管标识？

可以向API Management实例授予两种类型的标识：

系统分配的标识与你的服务绑定，如果删除服务，标识也会被删除。服务只能有一个系统分配的标识。
用户分配的标识是可分配给服务的独立Azure资源。服务可以有多个用户分配身份。

注意事项

Azure订阅位于 Microsoft Entra 租户中，而托管标识则特定于该租户。如果将订阅移动到其他目录，它们不会被更新。如果移动了订阅，则需要重新创建并重新配置标识。
API Management 的托管标识也特定于服务所在的 Azure 订阅。如果将服务移动到同一租户中的其他订阅，则需要重新创建并重新配置标识。

创建系统分配的托管标识

Azure portal

若要在Azure portal中设置托管标识，请创建API Management实例，然后启用该功能。

像平常一样在门户中创建API Management实例。在门户网站中转到它。
在左侧菜单中，在“安全性”下，选择“托管身份”。
在 “系统分配 ”选项卡上，将 “状态 ”更改为 “打开”。选择“保存” 。

Azure PowerShell

注意事项

建议使用 Azure Az PowerShell 模块与Azure交互。请参阅 Install Azure PowerShell 来开始使用。若要了解如何迁移到 Az PowerShell 模块，请参阅 Migrate Azure PowerShell从 AzureRM 迁移到 Az。

以下步骤将引导你创建API Management实例，并使用 Azure PowerShell 为其分配标识。

如果需要，请按照 Azure PowerShell 指南中的说明安装Azure PowerShell。然后运行 Connect-AzAccount -Environment AzureChinaCloud 以创建与Azure的连接。

使用以下代码创建具有系统分配的托管标识的实例。有关如何将Azure PowerShell与API Management配合使用的更多示例，请参阅 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）模板

可以通过在 ARM 模板资源定义中包含以下属性来创建具有系统分配标识的API Management实例：

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

此属性指示Azure为API Management实例创建和管理标识。

例如，完整的 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 Management实例的名称相同。

注意事项

API Management实例可以同时具有系统分配的标识和用户分配的标识。在这种情况下，该 type 属性为 SystemAssigned,UserAssigned.

使用托管身份配置 Key Vault 访问权限

如果要使用 API Management 从 Azure 密钥保管库访问证书，则需要以下配置。

配置访问权限到密钥保管库

在门户中，访问您的密钥保管库。
在左侧菜单中，选择设置>访问配置。请注意配置的权限模型。
根据权限模型，为 API Management 托管标识配置密钥库访问策略或 Azure RBAC 访问。

添加密钥保管库的访问策略：

在左侧菜单中，选择访问策略。
在访问策略页上，选择+ 创建。
在“ 权限 ”选项卡上的“ 机密权限”下，选择“ 获取和列出”，然后选择“ 下一步”。
在“主体”选项卡上搜索托管标识的资源名称，然后选择“下一步”。如果您使用的是系统自动分配的身份，则主体是您的 API Management 实例的名称。
再次选择“下一步”。在“查看 + 创建”选项卡上，选择“创建”。

配置 Azure RBAC 访问权限：

在左侧菜单中，选择Access control（IAM）。
在 Access control （IAM） 页上，选择添加角色分配。
在“Role 选项卡上，选择Key Vault证书用户。
在成员选项卡上，选择托管身份>+ 选择成员。
在“选择托管标识窗口中，选择系统分配的托管标识或与API Management实例关联的用户分配的托管标识，然后单击选择。
选择‹查看 + 分配›

关于Key Vault防火墙的要求

如果在key vault上启用了 Key Vault 防火墙，则必须满足以下要求：

必须使用API Management实例的系统分配托管标识以访问密钥保管库。
在Key Vault防火墙中，启用 Allow Trusted Microsoft Services 以绕过此防火墙选项。 API Management支持信任服务连接，以访问控制平面选项的密钥保管库。
确保在选择要添加到 Azure API Management 的证书或机密时，允许本地客户端 IP 地址临时访问密钥保管库。有关详细信息，请参阅配置Azure Key Vault网络设置。

完成配置后，可以在key vault防火墙中阻止客户端地址。

重要

从 2026 年 3 月开始，通过启用Allow Trusted Microsoft Services to bypass this firewall（允许受信任的 Microsoft 服务绕过此防火墙）的防火墙设置，从 API Management 网关到 Azure 服务的受信任服务连接将不再受支持。若要在此更改后继续从API Management网关访问这些服务，请确保选择其他受支持的网络访问选项。对于控制平面操作，您可以继续使用受信任的服务连接。了解详细信息。

虚拟网络要求

如果API Management实例部署在virtual network中，还配置以下网络设置：

启用service endpoint以便在 API Management 子网中使用 Key Vault。
配置一个网络安全组 (NSG) 规则，以允许指向 AzureKeyVault 和 AzureActiveDirectory 服务标记的出站流量。

有关详细信息，请参阅在虚拟网络中设置 API Management 时的网络配置。

支持使用系统分配标识的场景

下面是在 Azure API Management 中使用系统分配的托管标识的一些常见方案。

从Key Vault获取API Management实例的自定义 TLS/SSL 证书

可以使用API Management实例的系统分配标识来检索存储在Key Vault中的自定义 TLS/SSL 证书。然后，可以将这些证书分配给API Management实例中的自定义域。考虑以下注意事项：

机密的内容类型必须是 application/x-pkcs12。有关详细信息，请参阅域证书选项。
必须使用包含机密的Key Vault证书机密终结点。

重要

如果未提供证书的对象版本，API Management Key Vault更新后四小时内自动获取证书的任何较新版本。

以下示例演示了一个 ARM 模板，该模板使用 API 管理实例的系统分配托管标识从 Key 保管库检索自定义域名证书。

先决条件

一个配置了系统分配托管标识的 API 管理实例。若要创建实例，可以使用 Azure 快速入门模板。
同一资源组中的Key Vault实例。该实例必须托管一个证书，该证书将用作API Management中的custom domain证书。

模板包含以下步骤。

更新Key Vault实例的access策略，并允许API Management实例从中获取机密。
通过 Key Vault 实例中的证书，将实例更新为具有自定义域名的 API 管理。

运行模板时，请提供适合你的环境的参数值。

{
	"$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.cn/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 Management标识向后端进行身份验证

可以使用系统分配的标识通过 authentication-managed-identity 策略向后端服务进行身份验证。

使用系统分配的托管标识连接到 IP 防火墙后面的Azure资源

Microsoft的API管理作为以下资源的受信任服务。当防火墙允许设置 允许受信任的Microsoft服务绕过此防火墙时，此受信任状态使服务能够连接到防火墙后面的以下资源。将适当的 Azure 角色显式分配给资源实例的系统分配的托管标识之后，资源实例的访问范围将对应于分配给托管标识的 Azure 角色。

重要

自 2026 年 3 月起，允许受信任的 Microsoft 服务通过 API Management 网关连接到 Azure 服务的防火墙设置将不再受支持。若要在此更改后继续从 API Management 网关访问这些服务，请确保选择其他受支持的网络访问选项。对于控制平面操作，您可以继续使用受信任的服务连接。了解详细信息。

将事件记录到事件中心

可以配置和使用系统分配的托管标识来访问事件中心，从API管理实例记录事件。有关详细信息，请参阅如何在 Azure API Management 中将事件记录到事件中心。

创建用户分配的托管标识

注意事项

可以将API Management实例与多达 10 个用户分配的托管标识相关联。

Azure portal

若要在门户中设置托管标识，必须先创建API Management实例并创建用户分配的标识。然后完成以下步骤。

转到门户中的 API 管理实例。
在左侧菜单中，在“安全性”下，选择“托管身份”。
在“用户分配”选项卡上，选择“添加”。
查找之前创建的标识并选择它。选择“添加” 。

Azure PowerShell

注意事项

建议使用 Azure Az PowerShell 模块与Azure交互。请参阅 Install Azure PowerShell 以开始使用。若要了解如何迁移到 Az PowerShell 模块，请参阅 Migrate Azure PowerShell从 AzureRM 迁移到 Az。

以下步骤将引导你创建API Management实例，并使用 Azure PowerShell 为其分配标识。

如果需要，请按照 Azure PowerShell 指南中的说明安装Azure PowerShell。然后运行 Connect-AzAccount -Environment AzureChinaCloud 以创建与Azure的连接。

使用以下代码创建实例。有关如何将Azure PowerShell与API Management配合使用的更多示例，请参阅 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 Management实例：

"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 Management实例可以同时具有系统分配的标识和用户分配的标识。在这种情况下，该 type 属性将为 SystemAssigned,UserAssigned.

支持使用用户分配的托管标识的场景

下面是在Azure API Management中使用用户分配的托管标识的一些常见方案。

从Key Vault获取API Management实例的自定义 TLS/SSL 证书

可以使用用户分配的标识在API Management实例和Key Vault之间建立信任。然后，可以使用此信任来检索存储在Key Vault中的自定义 TLS/SSL 证书。然后，可以将这些证书分配给API Management实例中的自定义域。

重要

如果在您的密钥保管库上启用了 Key Vault防火墙，则无法使用用户分配的身份从API Management进行访问。可以改用系统分配的标识。有关详细信息，请参阅key vault 防火墙要求部分。

考虑以下注意事项：

机密的内容类型必须是 application/x-pkcs12。
必须使用包含机密的 Key Vault 证书密钥终结点。

重要

如果未提供证书的对象版本，API Management Key Vault更新后四小时内自动获取证书的任何较新版本。

存储和管理来自Key Vault的命名值

可以使用用户分配的托管身份来访问 Key Vault，以便在 API Management 策略中存储和管理机密。有关详细信息，请参阅在 Azure API Management 策略中使用命名值。

注意事项

如果在密钥保管库上启用了 Key Vault 防火墙，则不能使用用户分配的标识从 API Management 进行访问。可以改用系统分配的标识。有关详细信息，请参阅“密钥保管库防火墙要求”部分。

使用用户分配的标识向后端进行身份验证

可以使用用户分配的标识通过 authentication-managed-identity 策略向后端服务进行身份验证。

将事件记录到事件中心

可以配置和使用用户分配的托管标识来访问事件中心，以记录来自 API 管理实例的事件。有关详细信息，请参阅如何在 Azure API Management 中将事件记录到Azure Event Hubs。

删除身份

可以通过门户或 ARM 模板禁用功能，以与创建功能相同的方式移除系统分配的标识。可以单独删除用户分配的标识。若要删除所有标识，请将标识类型设置为 "None"。

以这种方式删除系统分配的标识也会将其从Microsoft Entra ID中删除。删除API Management实例时，系统分配的标识也会自动从Microsoft Entra ID中删除。

若要使用 ARM 模板删除所有标识，请更新本部分：

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

重要

如果API Management实例配置了来自Key Vault的自定义 SSL 证书，并且你尝试禁用托管标识，则请求将失败。

可以通过从Key Vault证书切换到内联编码的证书，然后禁用托管标识来解决此问题。有关详细信息，请参阅配置自定义域。

Last updated on 2026-03-10

通过

在 Azure API Management 中使用托管标识

创建系统分配的托管标识

Azure portal

Azure PowerShell

Azure Resource Manager （ARM） 模板

使用托管身份配置 Key Vault 访问权限

配置访问权限到密钥保管库

关于Key Vault防火墙的要求

虚拟网络要求

支持使用系统分配标识的场景

从Key Vault获取API Management实例的自定义 TLS/SSL 证书

先决条件

存储和管理来自Key Vault的命名值

使用API Management标识向后端进行身份验证

使用系统分配的托管标识连接到 IP 防火墙后面的Azure资源

将事件记录到事件中心

创建用户分配的托管标识

Azure portal

Azure PowerShell

ARM 模板

支持使用用户分配的托管标识的场景

从Key Vault获取API Management实例的自定义 TLS/SSL 证书

存储和管理来自Key Vault的命名值

使用用户分配的标识向后端进行身份验证

将事件记录到事件中心

删除身份

相关内容

其他资源

Azure Resource Manager （ARM）模板