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

2025-06-09

適用対象: すべての 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 を設定できます。

注

マネージド 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 の移行」を参照してください。

次の手順では、API Management インスタンスを作成し、Azure PowerShell を使用して ID を割り当てます。

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

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

既存のインスタンスを更新して 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 (ARM) テンプレート

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

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

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

注

API Management インスタンスは、システム割り当て ID とユーザー割り当て ID の両方を持つことができます。そのシナリオでは、 type プロパティが SystemAssigned,UserAssigned。

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

API Management を使用して Azure キーコンテナーから証明書にアクセスする場合は、次の構成が必要です。

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

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

キーコンテナーのアクセスポリシーを追加するには:

左側のメニューで、[アクセスポリシー] を選択します。
[アクセスポリシー] ページで、[+ 作成] を選択します。
[ アクセス許可 ] タブの [ シークレットのアクセス許可] で、[ 取得と 一覧表示] を選択し、[ 次へ] を選択します。
[ プリンシパル ] タブで [ プリンシパル] を選択し、マネージド ID のリソース名を検索して、[ 次へ] を選択します。システムによって割り当てられた ID を使用している場合、プリンシパルは API Management インスタンスの名前です。
もう一度 [次へ] を選択します [確認および作成] タブで、 [作成] を選択します。

Azure RBAC アクセスを構成するには:

左側のメニューで [アクセス制御 (IAM)] を選択します。
[アクセス制御 (IAM)] ページで、[ロールの割り当てを追加] を選択します。
[ロール] タブで、[キーコンテナー証明書ユーザー] を選択します。
[メンバー] タブで、[マネージド ID]>[+ Select members] (+ メンバーの選択) を選択します。
[ マネージド ID の選択 ] ウィンドウで、API Management インスタンスに関連付けられているシステム割り当てマネージド ID またはユーザー割り当てマネージド ID を選択し、[ 選択] をクリックします。
[レビューと割り当て] を選択します。

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 のネットワーク設定を構成する」を参照してください。

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

仮想ネットワークの要件

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

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

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

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

Azure API Management でシステム割り当てマネージド ID を使用する一般的なシナリオを次に示します。

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

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

シークレットのコンテンツタイプは application/x-pkcs12 である必要があります。詳細については、「ドメイン証明書のオプション」を参照してください。
シークレットを含む Key Vault 証明書シークレットエンドポイントを使用する必要があります。

重要

証明書のオブジェクトバージョンを指定しない場合、API Management は Key Vault で更新されてから 4 時間以内に新しいバージョンの証明書を自動的に取得します。

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

前提条件

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

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

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 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 の名前付き値を格納および管理する

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

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

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

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

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

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

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

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

注

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

Azure Portal

ポータルでマネージド ID を設定するには、まず API Management インスタンスを作成し、ユーザー割り当て ID を作成する必要があります。その後、次の手順を実行します。

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

Azure PowerShell

注

次の手順では、API Management インスタンスを作成し、Azure PowerShell を使用して ID を割り当てます。

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

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

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

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

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

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

ユーザー割り当て型を追加すると、インスタンスに指定されたユーザー割り当て ID を使用するように 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 の管理に使用される ID の一意識別子です。 clientId プロパティは、ランタイム呼び出し中に使用される ID を指定するために使用される、アプリケーションの新しい ID の一意識別子です。

注

API Management インスタンスは、システム割り当て ID とユーザー割り当て ID の両方を持つことができます。そのシナリオでは、 type プロパティが SystemAssigned,UserAssignedされます。

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

Azure API Management でユーザー割り当てマネージド ID を使用する一般的なシナリオを次に示します。

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

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

重要

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

次の考慮事項を考慮してください。

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

重要

Key Vault の名前付き値を格納および管理する

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

注

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

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

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

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

ID を削除する

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

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

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

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

重要

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

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

次の方法で共有

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

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

Azure Portal

Azure PowerShell

Azure Resource Manager (ARM) テンプレート

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

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

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

仮想ネットワークの要件

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

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

前提条件

Key Vault の名前付き値を格納および管理する

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

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

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

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

Azure Portal

Azure PowerShell

ARM テンプレート

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

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

Key Vault の名前付き値を格納および管理する

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

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

ID を削除する

関連コンテンツ

フィードバック

その他のリソース

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

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

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