Microsoft Entra アプリケーションを使用して製品と API に安全にアクセスする

適用対象: 開発者 |基本 |標準 |プレミアム

API Management では、クライアント資格情報フローを使用した製品 API への OAuth 2.0 アプリケーション ベースの組み込みアクセスがサポートされるようになりました。 この機能により、API マネージャーは Microsoft Entra ID アプリケーションを登録でき、OAuth 2.0 承認を通じて開発者向けの安全な API アクセスが合理化されます。

この機能を使用すると、次のようになります。

• API マネージャーは、アプリケーション ベースのアクセスを有効にするために製品プロパティを設定します。
• API マネージャーは、クライアント アプリケーションを Microsoft Entra ID に登録して、特定の製品へのアクセスを制限します。
• 開発者は、API Management 開発者ポータルを使用してクライアント アプリケーションの資格情報にアクセスできます。
• OAuth 2.0 クライアント資格情報フローを使用して、開発者またはアプリは API 要求に含めることができるトークンを取得します
• API 要求で提示されるトークンは、API Management ゲートウェイによって検証され、製品の API へのアクセスを承認します。

[前提条件]

• Premium、Standard、Basic、または Developer レベルにデプロイされた API Management インスタンス。 インスタンスをデプロイする必要がある場合は、「 API Management サービス インスタンスの作成」を参照してください。

• API Management インスタンス内の少なくとも 1 つの製品。少なくとも 1 つの API が割り当てられます。

  • 開発者ポータルから開発者がアクセスできるように、製品は 発行 済み状態である必要があります。
  • テストでは、既定の スターター 製品と、それに追加された Echo API を使用できます。
  • 製品を作成する場合は、「製品の 作成と発行」を参照してください。

• Microsoft Entra テナントで アプリケーション管理者 ロールを割り当てるための十分なアクセス許可。これには、少なくとも 特権ロール管理者ロールが 必要です。

• 必要に応じて、API Management インスタンスに 1 人以上の ユーザー を追加します。

• Azure PowerShell をローカルで使用する場合は、次のようにします。
  • Az PowerShell モジュールの最新バージョンをインストールします。
  • Connect-AzAccount コマンドレットを使用して、Azure アカウントに接続します。
• Azure Cloud Shell を使用する場合は、次のようにします。
  • 詳細については、Azure Cloud Shell の概要に関するページを参照してください。

マネージド ID を構成する

1. API Management インスタンスで API Management のシステム割り当てマネージド ID を有効にします。

2. ID を Microsoft Entra ID の アプリケーション管理者 RBAC ロールに割り当てます。 ロールを割り当てるには:

   1. ポータルにサインインし、Microsoft Entra ID に移動します。
   2. 左側のメニューで、管理>ロールと管理者 を選択します。
   3. [ アプリケーション管理者] を選択します。
   4. 左側のメニューで、[管理]>[割り当て]>[+ 割り当ての追加] を選択します。
   5. [ 割り当ての追加] ページで、名前 (API Management インスタンスの名前) で API Management インスタンスのマネージド ID を検索します。 マネージド ID を選択し、[ 追加] を選択します。

製品のアプリケーション ベースのアクセスを有効にする

製品の アプリケーション ベースのアクセス を有効にするには、次の手順に従います。 後の手順でクライアント アプリケーションに関連付けるためには、製品でこの設定を有効にする必要があります。

次の例では Starter 製品を使用しますが、少なくとも 1 つの API が割り当てられている発行済み製品を選択します。

1. アプリケーション機能のカスタム URL でポータルにサインインします: https://portal.azure.com/?feature.customPortal=false&Microsoft_Azure_ApiManagement=applications
2. API Management インスタンスに移動します。
3. 左側のメニューの [API] で [ 製品] を選択します。
4. スターター製品など、構成する製品を選択します。
5. 左側のメニューの [ 製品] で [ プロパティ] を選択します。
6. [ アプリケーション ベースのアクセス ] セクションで、 OAuth 2.0 トークン (最も安全) の設定を有効にします。
7. 必要に応じて、[ サブスクリプション キー ] 設定を有効にします。 アプリケーション ベースのアクセスとサブスクリプション要件の両方を有効にした場合、API Management ゲートウェイは、製品の API にアクセスするための OAuth 2.0 トークンまたはサブスクリプション キーを受け入れます。
8. 保存 を選択します。

アプリケーション ベースのアクセスを有効にすると、製品を表すバックエンド エンタープライズ アプリケーションが Microsoft Entra ID に作成されます。 バックエンド アプリケーション ID が製品の [プロパティ] ページに表示されます。

(省略可能)Microsoft Entra ID で製品アプリケーションの設定を確認する

必要に応じて、Microsoft Entra ID で作成されたバックエンド エンタープライズ アプリケーションの設定を確認して、製品を表します。

アプリケーションには、 APIMProductApplication<product-name> という形式で名前が付けられます。 たとえば、製品名が Starter の場合、アプリケーション名は APIMProductApplicationStarter です。 アプリケーションにはアプリ ロール が定義されています。

アプリの登録でアプリケーション設定を確認するには:

1. ポータルにサインインし、Microsoft Entra ID>Manage>App 登録に移動します。
2. [すべてのアプリケーション] を選択します。
3. API Management によって作成されたアプリケーションを検索して選択します。
4. 左側のメニューの [ 管理] で、[ アプリロール] を選択します。
5. 次のスクリーンショットに示すように、Azure API Management によって設定されたアプリケーション ロールを確認します。

クライアント アプリケーションを登録して製品にアクセスする

次に、1 つ以上の製品へのアクセスを制限するクライアント アプリケーションを登録します。

• 製品がクライアント アプリケーションに関連付けられるには、 アプリケーション ベースのアクセス が有効になっている必要があります。
• 各クライアント アプリケーションには、API Management インスタンスに 1 人のユーザー (所有者) がいます。 アプリケーションを介して製品 API にアクセスできるのは所有者だけです。
• 1 つの製品を複数のクライアント アプリケーションに関連付けることができます。

クライアント アプリケーションを登録するには:

1. アプリケーション機能のカスタム URL でポータルにサインインします: https://portal.azure.com/?feature.customPortal=false&Microsoft_Azure_ApiManagement=applications

2. API Management インスタンスに移動します。

3. 左側のメニューの [API] で、[ アプリケーション>+ アプリケーションの登録] を選択します。

4. [ アプリケーションの登録 ] ページで、次のアプリケーション設定を入力します。

   • 名前: アプリケーションの名前を入力します。
   • 所有者: API Management インスタンスのユーザーのドロップダウン リストから、アプリケーションの所有者を選択します。
   • 選択した製品へのアクセス権を付与する: 以前にアプリケーション ベースのアクセスが有効になっている API Management インスタンス内の 1 つ以上の製品を選択します。
   • 説明: 必要に応じて説明を入力します。

   

5. 登録 を選択します。

アプリケーションは、[アプリケーション ] ページの アプリケーションの一覧に追加されます。 クライアント ID などの詳細を表示するアプリケーションを選択 します。 製品 API を呼び出すトークンを生成するには、この ID が必要です。

クライアント シークレットを生成する

クライアント アプリケーションが OAuth 2.0 クライアント資格情報フローを使用するには、クライアント シークレットを生成する必要があります。 シークレットは 1 年間有効ですが、いつでも再生成できます。

1. [アプリケーション] ページ で 、作成したアプリケーションを選択します。

2. アプリケーションの [概要 ] ページで、[ クライアント シークレット] の横にある [ シークレットの追加] を選択します。

3. [ 新しいクライアント シークレット ] ページで、[ 生成] を選択します。

   クライアント シークレットが生成され、[ クライアント シークレット ] フィールドに表示されます。 シークレットの値をコピーし、安全に保存してください。 ページを閉じた後は、もう一度取得することはできません。

4. を選択してを閉じます。

(省略可能)Microsoft Entra ID でクライアント アプリケーションの設定を確認する

必要に応じて、Microsoft Entra ID でクライアント アプリケーションの設定を確認します。

アプリケーションには、 APIMApplication<product-name> という形式で名前が付けられます。 たとえば、製品名が Starter の場合、アプリケーション名は APIMApplicationStarter に似ています。

アプリの登録でアプリケーション設定を確認するには:

1. ポータルにサインインし、Microsoft Entra ID>Manage>App 登録に移動します。

2. [すべてのアプリケーション] を選択します。

3. API Management によって作成されたクライアント アプリケーションを検索して選択します。

4. 左側のメニューの [ 管理] で、[ API のアクセス許可] を選択します。

5. アプリケーションにバックエンド製品アプリケーションまたはアプリケーションにアクセスするためのアクセス許可があることを確認します。

   たとえば、クライアント アプリケーションが Starter 製品へのアクセスを許可する場合、アプリケーションには APIMProductApplicationStarter アプリケーションにアクセスするための Product.Starter.All アクセス許可があります。

   

開発者ポータルでアプリケーション設定を取得する

ユーザーは開発者ポータルにサインインして、所有しているクライアント アプリケーションを表示できます。

1. クライアント アプリケーションの所有者として設定されたユーザー アカウントを使用して、開発者ポータル (https://<your-apim-instance-name>.developer.azure-api.net) にサインインします。

2. 上部のナビゲーション メニューで、[アプリケーション] を選択 します。

3. ユーザーが所有するアプリケーションが一覧に表示されます。

4. クライアント ID、 クライアント シークレット、スコープなどの詳細を表示するアプリケーションを選択 します。 これらの値は、製品 API を呼び出すトークンを生成するために必要です。

   

トークンを作成し、API 呼び出しで使用する

製品に対してアプリケーション ベースのアクセスを有効にし、クライアント アプリケーションを登録すると、開発者またはアプリは、製品の API を呼び出すトークンを生成できます。 トークンは、要求の Authorization ヘッダーに含まれている必要があります。

たとえば、開発者またはアプリは、次の Azure PowerShell スクリプトを実行してクライアント アプリケーションを呼び出してトークンを生成し、そのトークンを使用して API Management で製品 API を呼び出すことができます。

クライアント アプリケーションを呼び出してトークンを生成する

# Replace placeholder values with your own values.

$clientId = "00001111-aaaa-2222-bbbb-3333cccc4444" # Client (application) ID of client application
$clientSecret = "******" # Retrieve secret of client application in developer portal
$scopeOfOtherApp = "api://55556666-ffff-7777-aaaa-8888bbbb9999/.default" # Value of Audience in product properties
$tenantId = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Directory (tenant) ID in Microsoft Entra ID

$body = @{
    grant_type    = "client_credentials"
    client_id     = $clientId
    client_secret = $clientSecret
    scope         = $scopeOfOtherApp
}
$response = Invoke-RestMethod -Method Post -Uri "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token" -ContentType "application/x-www-form-urlencoded" -Body $body
$token = $response.access_token

トークンを使用して製品 API を呼び出す

前の手順で生成されたトークンは、製品 API の呼び出しに使用されます。 トークンは要求の Authorization ヘッダーで渡されます。 API Management インスタンスはトークンを検証し、API へのアクセスを承認します。

次のスクリプトは、エコー API の呼び出しの例を示しています。

# Gatewate endpoint to call. Update with URI of API operation you want to call.
$uri = "https://<gateway-hostname>/echo/resource?param1=sample"
$headers = @{
   "Authorization" = "Bearer $token"  # $token is the token generated in the previous script.
}
$body = @{
    "hello" = "world"
} | ConvertTo-Json -Depth 5

$getresponse = Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/x-www-form-urlencoded" -Headers $headers -Body $body
Write-Host "Response:"
$getresponse | ConvertTo-Json -Depth 5

トラブルシューティング

ポータルでアプリケーションを登録するときの内部サーバー エラー

アプリケーションを一覧表示できない場合、またはポータルでアプリケーションを登録するときに内部サーバー エラーが発生する場合は、次を確認します。

• アプリケーション管理者ロールは、Microsoft Entra ID の API Management インスタンスのマネージド ID に割り当てられます。
• 次のアプリケーション機能のカスタム URL でポータルにサインインしています: https://portal.azure.com/?feature.customPortal=false&Microsoft_Azure_ApiManagement=applications。 この URL は、API Management のアプリケーション機能にアクセスするために必要です。

関連コンテンツ

• 成果物を作成して発行する
• API Management での API への認証と承認