Azure API Management でマネージド ID を使用する

[アーティクル]
03/31/2023

適用対象: すべての API Management レベル

この記事では、Azure API Management インスタンスのマネージド ID を作成する方法と、それを使って他のリソースにアクセスする方法について説明します。 Microsoft Entra ID によって生成されたマネージド ID によって、API Management インスタンスは、Azure Key Vault などの、Microsoft Entra で保護された他のリソースに簡単かつ安全にアクセスすることができます。この ID は Azure によって管理されるため、シークレットをプロビジョニングしたりローテーションしたりする必要はありません。マネージド ID の詳細については、「Azure リソースのマネージド ID とは」を参照してください。

API Management インスタンスには、次の 2 種類の ID を与えることができます。

システム割り当て ID はサービスに関連付けられ、サービスが削除されると削除されます。サービスでは、システム割り当て ID を 1 つだけ持つことができます。
ユーザー割り当て ID は、サービスに割り当てることができるスタンドアロン Azure リソースです。サービスでは、複数のユーザー割り当て ID を設定できます。

Note

マネージド ID は、Azure サブスクリプションがホストされている Microsoft Entra テナントに固有です。サブスクリプションが別のディレクトリに移動された場合は、更新されません。サブスクリプションが移動された場合は、ID を再作成して構成する必要があります。

システム割り当てマネージド ID を作成する

Azure portal

Azure portal でマネージド ID を設定するには、まず API Management インスタンスを作成し、その後、この機能を有効にします。

ポータルを使って通常の方法で API 管理インスタンスを作成します。ポータルでそれに移動します。
左側のメニューの [セキュリティ] で、[マネージド ID] を選択します。
[システム割り当て済み] タブで、 [状態] を [オン] に切り替えます。 [保存] を選択します。

Azure PowerShell

注意

Azure を操作するには、Azure Az PowerShell モジュールを使用することをお勧めします。作業を開始するには、Azure PowerShell のインストールに関する記事を参照してください。 Az PowerShell モジュールに移行する方法については、「AzureRM から Az への Azure PowerShell の移行」を参照してください。

次の手順では、Azure PowerShell を使用して、API Management インスタンスを作成し、それに対して ID を割り当てる方法について説明します。

必要に応じて、Azure PowerShell ガイドの手順を使用して、Azure PowerShell をインストールします。その後、Connect-AzAccount を実行して、Azure との接続を作成します。

システム割り当てマネージド ID を使用してインスタンスを作成するには、次のコードを使用します。 API Management インスタンスで Azure PowerShell を使用する方法の他の例については、「API Management 用の Azure 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

既存のインスタンスを更新して ID を作成することもできます。

# 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 テンプレート

システム割り当て ID を持った API Management インスタンスは、リソース定義に次のプロパティを含めることによって作成できます。

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

このプロパティは、API Management インスタンスの ID を作成して管理するよう Azure に命令するものです。

たとえば、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 プロパティは、その ID が属する Microsoft Entra テナントを識別します。 principalId プロパティは、インスタンスの新しい ID の一意識別子です。 Microsoft Entra ID 内では、サービスプリンシパルの名前は、API Management インスタンスに指定したものと同じになります。

Note

API Management インスタンスには、システム割り当て ID とユーザー割り当て ID の両方を同時に設定することができます。この場合、type プロパティは SystemAssigned,UserAssigned になります。

マネージド ID を使用して Key Vault アクセスを構成する

次の構成は、API Management が Azure Key Vault のシークレットと証明書にアクセスする際に必要なものです。

キーコンテナーへのアクセスを構成する

ポータルで、キーコンテナーに移動します。
左側のメニューで [アクセス構成] を選択し、構成されているアクセス許可モデルをメモします。
アクセス許可モデルに応じて、API Management マネージド ID のキーコンテナーアクセスポリシーまたは Azure RBAC アクセスを構成します。

キーコンテナーアクセスポリシーを追加する手順は、以下のとおりです。
1. 左側のメニューで、[アクセスポリシー] を選択します。
2. [アクセスポリシー] ページで、[+ 作成] を選択します。
3. [アクセス許可] タブの [シークレットのアクセス許可] で、[取得] と [リスト] を選択し、[次へ] を選択します。
4. [プリンシパル] タブの [Select principal] (プリンシパルの選択) で、マネージド ID のリソース名を検索し、[次へ] を選択します。システムによって割り当てられた ID を使用している場合、プリンシパルは API Management インスタンスの名前です。
5. もう一度 [次へ] を選択します [確認および作成] タブで、 [作成] を選択します。
Azure RBAC アクセスを構成する手順は、以下のとおりです。
1. 左側のメニューで [アクセス制御 (IAM)] を選択します。
2. [アクセス制御 (IAM)] ページで、[ロールの割り当てを追加] を選択します。
3. [ロール] タブで [キーコンテナーシークレットユーザー] を選択します。
4. [メンバー] タブで、[マネージド ID]>[+ Select members] (+ メンバーの選択) を選択します。
5. [Select managed identity] (マネージド ID の選択) ページで、API Management インスタンスに関連付けられているシステム割り当てマネージド ID またはユーザー割り当てマネージド ID を選択し、[選択] を選択します。
6. [レビューと割り当て] を選択します。

Key Vault ファイアウォールの要件

キーコンテナーで Key Vault ファイアウォールが有効になっている場合、追加要件は次のとおりです。

キーコンテナーにアクセスするには、API Management インスタンスのシステムによって割り当てられたマネージド ID を使用する必要があります。
Key Vault ファイアウォールで、 [Allow Trusted Microsoft Services to bypass this firewall](信頼された Microsoft サービスがこのファイアウォールをバイパスすることを許可する) オプションを有効にします。
Azure API Management に追加する証明書またはシークレットを選択するときに、ローカルクライアントの IP アドレスがキーコンテナーへの一時的なアクセスを許可されるようにする必要があります。詳細については、「Azure Key Vault のネットワーク設定を構成する」を参照してください。

構成が完了したら、キーコンテナーのファイアウォールでクライアントアドレスをブロックできます。

仮想ネットワークの要件

API Management インスタンスが仮想ネットワークにデプロイされている場合は、次のネットワーク設定も構成してください。

API Management サブネットで Azure Key Vault へのサービスエンドポイントを有効にします。
AzureKeyVault と AzureActiveDirectory のサービスタグへの送信トラフィックを許可するネットワークセキュリティグループ (NSG) 規則を構成します。

詳細については、VNet で Azure API Management を設定するときのネットワーク構成に関する記事を参照してください。

システム割り当て ID を使用したサポートされるシナリオ

API Management インスタンスのカスタム TLS/SSL 証明書を Azure Key Vault から取得する

API Management インスタンスのシステム割り当て ID を使用して、Azure Key Vault に格納されているカスタム TLS/SSL 証明書を取得できます。その後、これらの証明書を API Management インスタンスのカスタムドメインに割り当てることができます。以下の考慮事項に留意してください。

シークレットのコンテンツタイプは application/x-pkcs12 である必要があります。カスタムドメインの詳細については、証明書の要件を確認してください。
シークレットが含まれている Key Vault 証明書のシークレットエンドポイントを使用します。

重要

証明書のオブジェクトバージョンの指定がない場合は、より新しいバージョンの証明書が Key Vault にアップロードされた後、4 時間以内にそれが API Management によって自動的に取得されます。

次の例は、API Management サービスインスタンスのシステム割り当てマネージド ID を使用して、Key Vault からカスタムドメイン証明書を取得する Azure Resource Manager テンプレートを示しています。

前提条件

システム割り当てマネージド ID で構成された API Management サービスインスタンス。インスタンスを作成するには、Azure クイックスタートテンプレートを使用できます。
API Management のカスタムドメイン証明書として使用される証明書をホストする、同じリソースグループ内の Azure Key Vault インスタンス。

次のテンプレートには、次の手順が含まれています。

Azure Key Vault インスタンスのアクセスポリシーを更新し、そこからシークレットを取得することを API Management インスタンスに許可します。
Key Vault インスタンスからの証明書を使用してカスタムドメイン名を設定して API Management インスタンスを更新します。

テンプレートを実行するときは、ご自分の環境に適したパラメーター値を指定します。

{
	"$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 に名前付きの値を格納して管理する

API Management のポリシーに使用するシークレットは、システム割り当てマネージド ID を使用して Azure Key Vault にアクセスすることにより格納、管理できます。詳細については、「Azure API Management ポリシーで名前付きの値を使用する」を参照してください。

API Management ID を使用してバックエンドに対する認証を行う

システム割り当て ID を使用し、authentication-managed-identity ポリシーを通じて、バックエンドサービスに対する認証を行うことができます。

システム割り当てマネージド ID を使用して IP ファイアウォールの背後にある Azure リソースに接続する

API Management は、次のリソースに対する信頼された Microsoft サービスです。これを使用すると、サービスは、ファイアウォールの背後にある次のリソースに接続できるようになります。適切な Azure ロールをそのリソースインスタンスのシステム割り当てマネージド ID に明示的に割り当てると、そのインスタンスのアクセススコープは、マネージド ID に割り当てられた Azure ロールに対応します。

Azure サービス	Link
Azure Key Vault	Trusted-access-to-azure-key-vault
Azure Storage	Trusted-access-to-azure-storage
Azure Service Bus	Trusted-access-to-azure-service-bus
Azure Event Hubs	Trusted-access-to-azure-event-hub

イベントハブにイベントをログする

システム割り当てマネージド ID を構成して使用し、イベントハブにアクセスして API Management インスタンスからイベントをログ記録できます。詳しくは、「Azure API Management で Azure Event Hubs にイベントを記録する方法」をご覧ください。

ユーザー割り当てマネージド ID を作成する

Note

API Management インスタンスは、最大 10 個のユーザー割り当てマネージド ID に関連付けることができます。

Azure portal

このポータルでマネージド ID を設定するには、まず API Management インスタンスを作成し、ユーザー割り当て ID を作成します。次に、この機能を有効にします。

ポータルを使って通常の方法で API 管理インスタンスを作成します。ポータルでそれに移動します。
左側のメニューの [セキュリティ] で、[マネージド ID] を選択します。
[ユーザー割り当て済み] タブで、 [追加] を選択します。
先ほど作成した ID を検索して選択します。 [追加] を選択します。

Azure PowerShell

注意

次の手順では、Azure PowerShell を使用して、API Management インスタンスを作成し、それに対して ID を割り当てる方法について説明します。

必要に応じて、Azure PowerShell ガイドの手順を使用して、Azure PowerShell をインストールします。その後、Connect-AzAccount を実行して、Azure との接続を作成します。

次のコードを使用して、インスタンスを作成します。 API Management インスタンスで Azure PowerShell を使用する方法の他の例については、「API Management 用の Azure 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

既存のサービスを更新してサービスに ID を割り当てることもできます。

# 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 テンプレート

ID を持った API Management インスタンスは、リソース定義に次のプロパティを含めることによって作成できます。

"identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
        "<RESOURCEID>": {}
    }
}

ユーザー割り当ての種類を追加すると、インスタンスに対して指定されたユーザー割り当て ID を使用するように 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>"
        }
    }
}

principalId プロパティは、Microsoft Entra の管理に使用される ID の一意識別子です。 clientId プロパティは、ランタイム呼び出し中に使用される ID を指定するために使用される、アプリケーションの新しい ID の一意識別子です。

注意

ユーザー割り当てマネージド ID を使用したサポートされるシナリオ

API Management インスタンスのカスタム TLS/SSL 証明書を Azure Key Vault から取得する

ユーザーが割り当てた任意の ID を使用して、API Management インスタンスと Azure Key Vault 間で信頼を確立できます。その後、この信頼を使用して、Azure Key Vault に格納されているカスタム TLS/SSL 証明書を取得できます。その後、これらの証明書を API Management インスタンスのカスタムドメインに割り当てることができます。

重要

キーコンテナーで Key Vault ファイアウォールが有効になっている場合、API Management からのアクセスにユーザー割り当て ID は使用できません。代わりに、システム割り当て ID を使用してください。 Key Vault ファイアウォールで、[信頼された Microsoft サービスがこのファイアウォールをバイパスすることを許可する] オプションも有効になっている必要があります。

以下の考慮事項に留意してください。

シークレットのコンテンツタイプは application/x-pkcs12 である必要があります。
シークレットが含まれている Key Vault 証明書のシークレットエンドポイントを使用します。

重要

完全なテンプレートについては、ユーザー割り当て ID を使用した Key Vault ベースの SSL を使用する API Management に関するページをご覧ください。

このテンプレートで、以下をデプロイします。

Azure API Management インスタンス
Azure ユーザー割り当てマネージド ID
SSL/TLS 証明書を格納するための Azure Key Vault

デプロイを自動的に実行するには、次のボタンを選択します。

Azure Key Vault に名前付きの値を格納して管理する

API Management のポリシーに使用するシークレットは、ユーザー割り当てマネージド ID を使用して Azure Key Vault にアクセスすることにより格納、管理できます。詳細については、「Azure API Management ポリシーで名前付きの値を使用する」を参照してください。

Note

ユーザー割り当て ID を使用してバックエンドに対する認証を行う

ユーザー割り当て ID を使用し、authentication-managed-identity ポリシーを通じて、バックエンドサービスに対する認証を行うことができます。

イベントハブにイベントをログする

ユーザー割り当てマネージド ID を構成して使用し、イベントハブにアクセスして API Management インスタンスからイベントをログ記録できます。詳しくは、「Azure API Management で Azure Event Hubs にイベントを記録する方法」をご覧ください。

ID を削除する

ポータルまたは Azure Resource Manager テンプレートを使用して、作成したのと同じ方法で機能を無効にすることで、システム割り当て ID を削除できます。ユーザー割り当て ID は個別に削除することはできません。すべての ID を削除するには、ID の種類を "None" に設定します。

この方法でシステム割り当て ID を削除すると、それは Microsoft Entra ID からも削除されます。 API Management インスタンスが削除されると、システム割り当て ID も Microsoft Entra ID から自動的に削除されます。

Azure Resource Manager テンプレートを使用してすべての ID を削除するには、次のセクションを更新します。

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

重要

API Management インスタンスが Key Vault からのカスタム SSL 証明書を使用して構成されているときに、マネージド ID を無効にしようとすると、その要求は失敗します。

Azure Key Vault 証明書からインラインでエンコードされた証明書に切り替えて自分のブロックを解除した後、マネージド ID を無効にします。詳細については、「カスタムドメイン名を構成する」を参照してください。

次のステップ

詳細については、Azure リソースのマネージド ID について学びます。

Azure API Management でマネージド ID を使用する

システム割り当てマネージド ID を作成する

Azure portal

Azure PowerShell

Azure Resource Manager テンプレート

マネージド ID を使用して Key Vault アクセスを構成する

キー コンテナーへのアクセスを構成する

Key Vault ファイアウォールの要件

仮想ネットワークの要件

システム割り当て ID を使用したサポートされるシナリオ

API Management インスタンスのカスタム TLS/SSL 証明書を Azure Key Vault から取得する

前提条件

Azure Key Vault に名前付きの値を格納して管理する

API Management ID を使用してバックエンドに対する認証を行う

システム割り当てマネージド ID を使用して IP ファイアウォールの背後にある Azure リソースに接続する

イベント ハブにイベントをログする

ユーザー割り当てマネージド ID を作成する

Azure portal

Azure PowerShell

Azure Resource Manager テンプレート

ユーザー割り当てマネージド ID を使用したサポートされるシナリオ

API Management インスタンスのカスタム TLS/SSL 証明書を Azure Key Vault から取得する

Azure Key Vault に名前付きの値を格納して管理する

ユーザー割り当て ID を使用してバックエンドに対する認証を行う

イベント ハブにイベントをログする

ID を削除する

次のステップ

その他のリソース

キーコンテナーへのアクセスを構成する

イベントハブにイベントをログする

イベントハブにイベントをログする