在 Azure APIM 中使用受控識別

發行項
04/04/2024

適用於：所有 API 管理層

本文說明如何為 Azure API 管理執行個體建立受控識別，以及如何將其用來存取其他資源。 Microsoft Entra ID 所產生的受控識別可讓您的 APIM 執行個體輕鬆安全地存取其他受 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 的連線。

使用下列程式碼來建立具有系統指派的受控識別執行個體。如需了解 API 管理執行個體如何搭配使用Azure PowerShell 的其他範例，請參閱 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 範本

您可以在資源定義中包含以下屬性，來建立具有系統指派身分識別的「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 ID 內，服務主體名稱與您提供的 APIM 執行個體名稱相同。

注意

一個 API 管理執行個體可同時有系統指派和使用者指派的身分識別。在此情況下，type 屬性將會是 SystemAssigned,UserAssigned。

使用受控識別設定 Key Vault 存取

下列是 APIM 從 Azure 金鑰保存庫存取祕密和憑證所需的設定。

設定金鑰保存庫存取權

在入口網站中，瀏覽至您的金鑰保存庫。
從左側功能表中選取 [存取設定]，並記下已設定的 [權限模型]。
根據權限模型，為 APIM 受控識別設定金鑰保存庫存取原則或 Azure RBAC 存取權。

若要新增金鑰保存庫存取原則：
1. 在左側功能表中，選取 [存取原則]。
2. 在 [存取原則] 頁面上，選取 [+ 建立]。
3. 在 [權限] 索引標籤的 [祕密權限] 下，選取 [取得] 與 [列出]，然後選取 [下一步]。
4. 在 [主體] 索引標籤的 [選取主體] 中，搜尋受控識別的資源名稱，然後選取 [下一步]。如果您使用系統指派的身分識別，則主體是您 API 管理執行個體的名稱。
5. 再次選取 [下一步]。在 [檢閱 + 建立] 索引標籤中，選取 [建立]。
若要設定 Azure RBAC 存取權：
1. 在左側功能表中，選取 [存取控制 (IAM)]。
2. 在 [存取控制 (IAM)] 頁面上，選取 [新增角色指派]。
3. 在 [角色] 索引標籤上，選取 [金鑰保存庫憑證使用者]。
4. 在 [成員] 索引標籤上，選取 [受控識別]>[+ 選取成員]。
5. 在 [選取受控識別] 頁面上，選取系統指派的受控識別或與 APIM 執行個體相關聯的使用者指派受控識別，然後選取 [選取]。
6. 選取檢閱+指派。

金鑰保存庫防火牆的需求

如果您的金鑰保存庫已啟用金鑰保存庫防火牆，則下列為其他需求：

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

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

虛擬網路需求

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

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

如需詳細資料，請參閱在 VNet 中設定 Azure API 管理時的網路設定。

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

自 Azure Key Vault 取得 API 管理執行個體的自訂 TLS/SSL 憑證

您可使用 API 管理執行個體的系統指派身分識別來擷取 Azure Key Vault 所儲存的自訂 TLS/SSL 憑證。接著便可將這些憑證指派給 API 管理執行個體的自訂網域。請記住下列考量：

秘密的內容類型必須為 application/x-pkcs12。深入了解自訂網域憑證需求。
使用包含秘密的 Key Vault 憑證秘密端點。

重要

若未提供憑證的物件版本，API 管理將會在Key Vault 更新憑證後四小時內，自動取得新版本憑證。

下列範例顯示 Azure Resource Manager 範本，此範本會使用 API 管理服務執行個體的系統指派的受控識別，從 Key Vault 擷取自訂網域憑證。

必要條件

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

下列範本包含以下步驟。

更新 Azure 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 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 管理原則的祕密。如需詳細資訊，請參閱在 Azure API 管理原則中使用具名值。

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

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

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

API 管理屬於下列資源的受信任 Microsoft 服務。這可讓服務連線至防火牆後的下列資源。在您將適當 Azure 角色明確指派給該資源執行個體的系統指派的受控識別後，該執行個體的存取範圍便會對應至指派給受控識別的 Azure 角色。

Azure Service	連結
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

將事件記錄到事件中樞

您可以設定並使用系統指派的受控識別來存取事件中樞，以記錄來自 APIM 執行個體的事件。如需詳細資訊，請參閱如何在 Azure APIM 中將事件記錄到 Azure 事件中樞。

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

注意

一個 API 管理執行個體最多可與 10 個使用者指派的受控識別建立關聯。

Azure 入口網站

若要在入口網站中設定受控識別，則須先建立 API 管理執行個體，再建立使用者指派的身分識別。然後，啟用該功能。

像平常一樣在入口網站中建立 API 管理執行個體。在入口網站中瀏覽至該執行個體。
在 [安全性] 下的左側功能表中，選取 [受控識別]。
在 [使用者指派] 索引標籤上，選取 [新增]。
搜尋先前已建立的身分識別並選取。選取 [新增]。

Azure PowerShell

注意

下列步驟將逐步引導您建立 API 管理執行個體，並使用 Azure PowerShell 為其指派身分識別。

視需要，您可使用 Azure PowerShell 指南中的指示來安裝 Azure PowerShell。接著執行 Connect-AzAccount 以建立與 Azure 的連線。

使用下列程式碼來建立執行個體。如需了解 API 管理執行個體如何搭配使用Azure PowerShell 的其他範例，請參閱 API 管理 PowerShell 範例。

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

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

注意

一個 API 管理執行個體可同時有系統指派和使用者指派的身分識別。在此情況下，type 屬性將會是 SystemAssigned,UserAssigned。

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

自 Azure Key Vault 取得 API 管理執行個體的自訂 TLS/SSL 憑證

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

重要

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

請記住下列考量：

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

重要

若未提供憑證的物件版本，API 管理將會在Key Vault 更新憑證後四小時內，自動取得新版本憑證。

如需完整範本，請參閱使用者指派的身分識別搭配使用 KeyVault 型 SSL 的 API 管理。

在此範本中，您將部署：

Azure API 管理執行個體
Azrue 使用者指派的受控識別
儲存 SSL/TLS 憑證的 Azure Key Vault

若要自動執行部署，請選取下列按鈕：

從 Azure Key Vault 儲存和管理具名值

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

注意

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

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

將事件記錄到事件中樞

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

移除身分識別

若要移除系統指派的身分識別，您可透過入口網站或 Azure Resource Manager 範本，依先前建立該功能的方式停用。使用者指派的身分識別可以個別移除。如要移除所有身分識別，請將身分識別類型設為"None"。

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

如要使用 ARM 範本來移除所有身分識別，請更新本區段：

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

重要

若 API 管理執行個體設定為 Key Vault 的自訂 SSL 憑證，且您嘗試停用受控識別，要求將會失敗。

解除封鎖的方式為從 Azure Key Vault 憑證切換為內嵌編碼憑證，接著停用該受控識別。如需詳細資訊，請參閱設定自訂網域名稱。

下一步

深入了解 Azure 資源的受控識別：

Share via

在 Azure APIM 中使用受控識別

建立系統指派的受控識別

Azure 入口網站

Azure PowerShell

Azure Resource Manager 範本

使用受控識別設定 Key Vault 存取

設定金鑰保存庫存取權

金鑰保存庫防火牆的需求

虛擬網路需求

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

自 Azure Key Vault 取得 API 管理執行個體的自訂 TLS/SSL 憑證

必要條件

從 Azure Key Vault 儲存和管理具名值

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

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

將事件記錄到事件中樞

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

Azure 入口網站

Azure PowerShell

Azure Resource Manager 範本

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

自 Azure Key Vault 取得 API 管理執行個體的自訂 TLS/SSL 憑證

從 Azure Key Vault 儲存和管理具名值

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

將事件記錄到事件中樞

移除身分識別

下一步

其他資源