次の方法で共有


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

適用対象: すべての 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 を再作成して構成する必要があります。

Note

現在、この機能はワークスペースでは使用できません。

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

Azure portal

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

  1. ポータルを使って通常の方法で API 管理インスタンスを作成します。 ポータルでそれに移動します。

  2. 左側のメニューの [セキュリティ] で、[マネージド ID] を選択します。

  3. [システム割り当て済み] タブで、 [状態][オン] に切り替えます。 [保存] を選択します。

    システム割り当てマネージド ID を有効化するための選択項目

Azure PowerShell

注意

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

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

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

  2. システム割り当てマネージド 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 のシークレットと証明書にアクセスする際に必要なものです。

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

  1. ポータルで、キー コンテナーに移動します。

  2. 左側のメニューで [アクセス構成] を選択し、構成されているアクセス許可モデルをメモします。

  3. アクセス許可モデルに応じて、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 インスタンス。

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

  1. Azure Key Vault インスタンスのアクセス ポリシーを更新し、そこからシークレットを取得することを API Management インスタンスに許可します。
  2. 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 を作成します。 次に、この機能を有効にします。

  1. ポータルを使って通常の方法で API 管理インスタンスを作成します。 ポータルでそれに移動します。

  2. 左側のメニューの [セキュリティ] で、[マネージド ID] を選択します。

  3. [ユーザー割り当て済み] タブで、 [追加] を選択します。

  4. 先ほど作成した ID を検索して選択します。 [追加] を選択します。

    ユーザー割り当てマネージド ID を有効化するための選択項目

Azure PowerShell

注意

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

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

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

  2. 次のコードを使用して、インスタンスを作成します。 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 の一意識別子です。

注意

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

ユーザー割り当てマネージド 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 証明書のシークレット エンドポイントを使用します。

重要

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

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

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

Note

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

ユーザー割り当て 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 について学びます。