在 Azure APIM 中使用受控識別

2025-06-02

適用於：所有 APIM 層

本文說明如何建立 Azure API 管理實例的受控識別，以及如何使用它來存取其他資源。 Microsoft Entra ID 所產生的受控識別可讓 API 管理輕鬆且安全地存取受 Microsoft Entra 保護的其他資源，例如 Azure Key Vault。 Azure 會管理這些身分識別，因此您不需要布建或輪替任何秘密。如需受控識別的詳細資訊，請參閱什麼是適用於 Azure 資源的受控識別？

API 管理執行個體可授與兩個類型的身分識別：

系統指派的身分識別會繫結至您的服務，若刪除服務則會一併刪除。服務僅能有一個系統指派的身分識別。
使用者指派的身分識別是一項獨立 Azure 資源，可指派給您的服務。服務可有多個使用者指派的身分識別。

注意

受管理的身分識別是專屬於您的 Azure 訂用帳戶所裝載的 Microsoft Entra 租戶。如果訂用帳戶移至不同的目錄，則其不會更新這些訂用帳戶。如果已移動訂用帳戶，您必須重新建立並重新設定身分識別。

注意

目前，無法在工作區中使用此功能。

建立系統指派的受控識別

Azure 入口網站

若要在 Azure 入口網站中設定受控識別，請建立 API 管理實例，然後啟用此功能。

像平常一樣在入口網站中建立 API 管理執行個體。在入口網站中進入該頁面。
在 [安全性] 下的左側功能表中，選取 [受控識別]。
在 系統指派 標籤上，將狀態變更為開啟。選取 [儲存]。

Azure PowerShell

注意

建議您使用 Azure Az PowerShell 模組來與 Azure 互動。若要開始使用，請參閱安裝 Azure PowerShell (部分機器翻譯)。若要了解如何移轉至 Az PowerShell 模組，請參閱將 Azure PowerShell 從 AzureRM 移轉至 Az。

下列步驟會引導您建立 API 管理實例，並使用 Azure PowerShell 為其指派身分識別。

如果您需要，請遵循 Azure PowerShell 指南中的指示來安裝 Azure PowerShell。接著執行 Connect-AzAccount 以建立與 Azure 的連線。

使用下列程式代碼來建立具有系統指派受控識別的實例。如需如何使用 Azure PowerShell 與 API 管理的詳細資訊，請參閱 API 管理 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"
}

此屬性會指示 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 內，服務主體名稱與您提供的 APIM 執行個體名稱相同。

注意

API 管理實例可以同時擁有系統指派和使用者指派的身分識別。在該案例中，type 屬性為 SystemAssigned,UserAssigned。

使用託管識別配置 Key Vault 存取

如果您想要使用 API 管理從 Azure 金鑰保存庫存取憑證，則需要下列設定。

設定金鑰保存庫存取權

在入口平台中，前往您的金鑰保存庫。
在左側功能表中，選取 [ 存取設定]。請注意已配置的許可權模型。
根據權限模型，為 APIM 受控識別設定金鑰保存庫存取原則或 Azure RBAC 存取權。

若要新增金鑰保存庫存取原則：

在左側功能表中，選取 [存取原則]。
在 [ 存取原則] 頁面上，選取 [+ 建立]。
在 [ 許可權] 索引標籤的 [ 秘密許可權] 底下，選取 [取得 和列表]，然後選取 [ 下一步]。
在 [ 主體] 索引標籤上，選取 [ 主體]，搜尋受控識別的資源名稱，然後選取 [ 下一步]。如果您使用系統指派的身分識別，則主體是您 API 管理執行個體的名稱。
再次選取 [下一步]。在 [檢閱 + 建立] 索引標籤中，選取 [建立]。

若要設定 Azure RBAC 存取：

在左側功能表中，選取 [存取控制 (IAM)]。
在 [存取控制 (IAM)] 頁面上，選取 [新增角色指派]。
在 [角色] 索引標籤上，選取 [Key Vault 憑證使用者]。
在 [成員] 索引標籤上，選取 [受控識別]>[+ 選取成員]。
在 [ 選取受控識別 ] 視窗中，選取系統指派的受控識別或與您 API 管理實例相關聯的使用者指派受控識別，然後按兩下 [ 選取]。
選取檢閱+指派。

金鑰保存庫防火牆的需求

如果您的金鑰保存庫已啟用 Key Vault 防火牆，您必須符合下列需求：

您必須使用 API 管理實體的系統指派受控識別來存取密鑰保存庫。
在金鑰保存庫防火牆中，啟用 [允許信任的 Microsoft 服務略過此防火牆] 選項。
當您選取要新增至 Azure API 管理的憑證或祕密時，請確定您的本機用戶端 IP 位址可以暫時存取金鑰保存庫。如需詳細資訊，請參閱設定 Azure Key Vault 網路設定。

完成設定之後，您可以在金鑰保存庫防火牆中封鎖客戶端位址。

虛擬網路需求

如果 API 管理執行個體已部署在虛擬網路中，也請設定下列網路設定：

在 API 管理子網上啟用 Key Vault 的服務端點。
設定網路安全性群組 (NSG) 規則，以允許對 AzureKeyVault 和 AzureActiveDirectory 服務標籤的輸出流量。

如需詳細資訊，請參閱在虛擬網路中設定 API 管理時的網路組態。

使用系統指派身分識別的支援案例

以下是在 Azure API 管理中使用系統指派受控識別的一些常見案例。

從 Key Vault 取得 API 管理實例的自定義 TLS/SSL 憑證

您可以使用 API 管理實例的系統指派身分識別來擷取儲存在 Key Vault 中的自定義 TLS/SSL 憑證。接著便可將這些憑證指派給 API 管理執行個體的自訂網域。將這些考慮納入考慮：

秘密的內容類型必須為 application/x-pkcs12。如需詳細資訊，請參閱網域憑證選項。
您必須使用包含秘密的 Key Vault 憑證秘密端點。

重要

如果您未提供憑證的物件版本，API 管理會在 Key Vault 中更新憑證後四小時內自動取得任何較新版本的憑證。

下列範例顯示 ARM 範本，該範本會使用 API 管理實例的系統指派受控識別，從 Key Vault 擷取自定義網域憑證。

必要條件

使用系統指派的受控識別設定的 API 管理實例。若要建立執行個體，您可以使用 Azure 快速入門範本。
相同資源群組中的 Key Vault 實例。執行個體必須托管憑證，該憑證將在 API 管理中用作自定義網域憑證。

範本包含下列步驟。

更新 Key Vault 實例的存取原則，並允許 API 管理實例從中取得秘密。
透過來自 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.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 管理原則中使用具名值。

使用 API 管理身分識別驗證後端

您可以使用系統指派的身分識別，透過 authentication-managed-identity 原則向後端服務進行驗證。

使用系統指派的受控識別連線到IP防火牆後方的 Azure 資源

API 管理屬於下列資源的受信任 Microsoft 服務。此信任狀態可讓服務連線到防火牆後方的下列資源。明確將適當的 Azure 角色指派給資源實例的系統指派受控識別之後，實例的存取範圍會對應至指派給受控識別的 Azure 角色。

將事件記錄到事件中樞

您可以設定並使用系統指派的受控識別來存取事件中樞，以記錄來自 API 管理實例的事件。如需詳細資訊，請參閱如何在 Azure API 管理中將事件記錄至事件中樞。

建立使用者指派的受控識別

注意

您可以將 API 管理實例與多達 10 個使用者指派的受控識別產生關聯。

Azure 入口網站

若要在入口網站中設定受控識別，您必須先建立 API 管理實例，並建立使用者指派的身分識別。然後完成下列步驟。

請前往管理平台中的您的 API 管理環境。
在 [安全性] 下的左側功能表中，選取 [受控識別]。
在 [使用者指派] 索引標籤上，選取 [新增]。
搜尋先前已建立的身分識別並選取。選取 [新增]。

Azure PowerShell

注意

下列步驟會引導您建立 API 管理實例，並使用 Azure PowerShell 為其指派身分識別。

如果您需要，請遵循 Azure PowerShell 指南中的指示來安裝 Azure PowerShell。接著執行 Connect-AzAccount 以建立與 Azure 的連線。

使用下列程式碼來建立執行個體。如需如何使用 Azure PowerShell 與 API 管理的詳細資訊，請參閱 API 管理 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>"
        }
    }
}

針對 Microsoft Entra 管理所用的身分識別，principalId 屬性是唯一識別碼。 clientId 屬性為應用程式新身分識別的唯一識別碼，用於指定執行階段呼叫期間要使用的身分識別。

注意

API 管理實例可以同時擁有系統指派和使用者指派的身分識別。在該案例中，屬性 type 會是 SystemAssigned,UserAssigned。

使用使用者指派受控識別的支援案例

以下是在 Azure API 管理中使用使用者指派受控識別的一些常見案例。

從 Key Vault 取得 API 管理實例的自定義 TLS/SSL 憑證

您可以使用使用者指派的身分識別來建立 API 管理實例與 Key Vault 之間的信任。接著，此信任可用來擷取儲存在Key Vault中的自定義TLS/SSL 憑證。接著便可將這些憑證指派給 API 管理執行個體的自訂網域。

重要

如果您的金鑰保存庫已啟用 Key Vault 防火牆，則您無法使用使用者指派的身分識別以從 API 管理進行存取。您可以改用系統指派的身分識別。在 Key Vault 防火牆中，必須啟用 [允許信任Microsoft服務略過此防火牆 選項。

將這些考慮納入考慮：

秘密的內容類型必須為 application/x-pkcs12。
您必須使用包含秘密的 Key Vault 憑證秘密端點。

重要

如果您未提供憑證的物件版本，API 管理會在 Key Vault 中更新憑證後四小時內自動取得任何較新版本的憑證。

從 Key Vault 中儲存和管理具名的值

您可以使用使用者指派的受控識別來存取 Key Vault，以儲存和管理秘密，以用於 API 管理原則。如需詳細資訊，請參閱在 Azure API 管理原則中使用具名值。

注意

使用使用者指派的身分識別驗證後端

您可以使用使用者指派的身分識別，透過 authentication-managed-identity 原則向後端服務進行驗證。

將事件記錄到事件中樞

您可以設定並使用使用者指派的受控識別來存取事件中樞，以記錄來自 API 管理實例的事件。如需詳細資訊，請參閱如何在 Azure APIM 中將事件記錄到 Azure 事件中樞。

移除身分識別

您可以透過入口網站或 ARM 範本，以與建立功能相同的方式來移除系統指派的身分識別。使用者指派的身分識別可以個別移除。如要移除所有身分識別，請將身分識別類型設為"None"。

以這種方式移除系統指派的身分識別，也會將它從Microsoft Entra ID刪除。刪除 APIM 執行個體時，系統指派的身分識別也會從 Microsoft Entra ID 自動移除。

若要使用 ARM 範本移除所有身分識別，請更新本節：

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

重要

如果 API 管理實例是使用來自 Key Vault 的自定義 SSL 憑證來設定，而且您嘗試停用受控識別，要求就會失敗。

您可以從 Key Vault 憑證切換至內嵌編碼憑證，然後停用受控識別，以解決此問題。如需詳細資訊，請參閱設定自訂網域名稱。

共用方式為

在 Azure APIM 中使用受控識別

建立系統指派的受控識別

Azure 入口網站

Azure PowerShell

Azure Resource Manager (ARM) 範例

使用託管識別配置 Key Vault 存取

設定金鑰保存庫存取權

金鑰保存庫防火牆的需求

虛擬網路需求

使用系統指派身分識別的支援案例

從 Key Vault 取得 API 管理實例的自定義 TLS/SSL 憑證

必要條件

從 Key Vault 中儲存和管理具名的值

使用 API 管理身分識別驗證後端

使用系統指派的受控識別連線到IP防火牆後方的 Azure 資源

將事件記錄到事件中樞

建立使用者指派的受控識別

Azure 入口網站

Azure PowerShell

ARM 範本

使用使用者指派受控識別的支援案例

從 Key Vault 取得 API 管理實例的自定義 TLS/SSL 憑證

從 Key Vault 中儲存和管理具名的值

使用使用者指派的身分識別驗證後端

將事件記錄到事件中樞

移除身分識別

相關內容

意見反應

其他資源