資格情報マネージャーを構成する - バックエンド API へのユーザー委任アクセス

[アーティクル]
11/22/2023

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

この記事では、アクセス許可の委任によるバックエンド OAuth 2.0 API の利用を Microsoft Entra ユーザーまたはグループに許可するマネージド接続について、構成と使用の大まかな手順を説明します。認証されたユーザーの代理となるクライアントアプリ (またはボット) に、セキュリティ保護されたバックエンドオンラインリソースへのアクセスを提供する必要がある場合 (例: メールの確認、注文の送信など) は、以下の手順に従います。

シナリオの概要

Note

このシナリオは、付与タイプ [承認コード] を使用して構成された認証情報プロバイダにのみ適用されます。

このシナリオでは、Microsoft Entra ユーザーまたはグループの代理となるクライアントアプリ (またはボット) にバックエンド API へのアクセスを提供するマネージド接続を構成します。たとえば、静的な Web アプリからバックエンドの GitHub API を利用し、特定のサインイン済みユーザーが持っている非公開データにアクセスする用途などが考えられます。このシナリオの説明図を示します。

ユーザーの委任されたアクセス許可のプロセスフローを示す図。

ユーザーは、アプリに対し、セキュリティ保護されたリソースに自分の代理としてアクセスすることの承認を与える必要があります。承認するには自分の ID を認証する必要があります
アプリは、ユーザーの代理として操作を実行するために外部バックエンドサービス (例: Microsoft Graph、GitHub など) を呼び出します
個々の外部サービスは、それぞれの方法で呼び出しのセキュリティを確保しています。たとえば、ユーザーを一意に識別するユーザートークンなどを使用します
アプリは、外部サービスへの呼び出しをセキュリティで保護するために、ユーザーにサインインを求め、ユーザーのトークンを取得する必要があります
構成の一環として、API Management インスタンスの資格情報マネージャーを使用して資格情報プロバイダーが登録されます。資格情報プロバイダーには、使用する ID プロバイダーに関する情報と、有効な OAuth クライアント ID およびシークレット、有効にする OAuth スコープ、その ID プロバイダーに必要な他の接続メタデータが格納されています。
また、ユーザーのサインインを補助する目的と、管理用にユーザートークンを取得する目的のために、接続が作成されます

前提条件

アプリの登録を作成し、アプリのアクセス許可に対する管理者の同意を付与するためのアクセス許可を持つ Microsoft Entra テナントへのアクセス。詳細情報

独自の開発者テナントを作成する場合は、Microsoft 365 開発者プログラムにサインアップできます。
委任するアクセス許可の対象であるテナント内の、1 つまたは複数のユーザーまたはグループ。
実行中の API Management インスタンス。必要に応じて、Azure API Management インスタンスを作成します。
ユーザーまたはグループの代理によってアクセスされるバックエンド OAuth 2.0 API。

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

手順 1: Azure API Management データプレーンサービスプリンシパルをプロビジョニングする

ユーザーまたはグループの使用するアクセス許可を委任できるようにするために、Azure API Management データプレーンサービスプリンシパルをプロビジョニングします。 Azure PowerShell を使用してサービスプリンシパルをプロビジョニングするには、以下の手順を実行します。

Azure PowerShell にサインインします。
AzureAD モジュールがまだインストールされていない場合は、次のコマンドでインストールします。
```
Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force
```
次のコマンドでテナントに接続します。
```
Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"
```
サインインが求められたら、テナントの管理者アカウントの資格情報を使用してサインインします。
次のコマンドで、Azure API Management データプレーンサービスプリンシパルをプロビジョニングします。
```
New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"
```

手順 2: Microsoft Entra アプリ登録を作成する

ユーザー委任を使用する Microsoft Entra ID アプリケーションを作成し、そのアプリに、API Management の接続を読み取るための適切なアクセス許可を付与します。

テナント内の十分なアクセス許可を持つアカウントを使用して Azure portal にサインインします。
Azure サービスで、Microsoft Entra ID を検索します。
左のメニューで [アプリの登録] を選択し、[+ 新規登録] を選択します。
[アプリケーションの登録] ページで、アプリケーションの登録の設定を入力します。
1. [名前] に、アプリのユーザーに対して表示するわかりやすい名前 (例: "UserPermissions") を入力します。
2. [サポートされているアカウントの種類] で、実際のシナリオに適したオプションを選択します。たとえば、[この組織ディレクトリのみに含まれるアカウント (シングルテナント)] を選択します。
3. [リダイレクト URI] を [Web] に設定し、「https://www.postman-echo.com/get」と入力します。
左側のメニューで [API のアクセス許可] を選択してから、[+アクセス許可の追加] を選択します。
1. [所属する組織で使用している API] タブを選択し、「Azure API Management データプレーン」と入力して選択します。
2. [アクセス許可] で、[Authorizations.Read] を選択し、[アクセス許可の追加] を選択します。
左側のメニューで [概要] を選択します。 [概要] ページで、[アプリケーション (クライアント) ID] の値を記録しておきます。この値は後の手順で必要になります。
左のメニューで [証明書とシークレット] を選択し、[+ 新しいクライアントシークレット] を選択します。
1. [Description](説明) を入力します。
2. [有効期限] のオプションを選択します。
3. [追加] を選択します。
4. ページから離れる前に、クライアントシークレットの値をコピーします。後の手順で必要になります。

手順 3: API Management の資格情報プロバイダーを構成する

portal にサインインし、API Management インスタンスに移動します。
左側のメニューで、[資格情報マネージャー] を選択し、[+ 作成] を選択します。
[資格情報プロバイダーの作成] ページで、使用する API の資格情報プロバイダーの設定を入力します。このシナリオでは、[付与タイプ] の選択を [承認コード] にする必要があります。詳細については、資格情報マネージャーでの資格情報プロバイダーの構成に関するページを参照してください。
［作成］ を選択します
OAuth リダイレクト URL の確認を求めるメッセージが表示されたら、アプリの登録で入力した URL と一致することを確認し、[はい] を選択します。

手順 4: 接続を構成する

資格情報プロバイダーを作成した後は、プロバイダーへの接続を追加します。 [接続] タブで、接続に関する以下の手順を実行します。

[接続名] を入力し、[保存] を選択します。
[ステップ 2: 接続にログイン] で、資格情報プロバイダーにログインするためのリンクを選択します。アクセスの承認に関する手順をここで完了してから、API Management に戻ります。
[ステップ 3: この接続 (アクセスポリシー) にアクセスできるユーザーを決定する] で、[+ 追加] を選択します。実際の委任シナリオに応じて、[ユーザー] または [グループ] を選択します。
[項目の選択] ウィンドウで、以下の順に選択操作を実行します。
1. まず、追加する 1 人または複数のユーザー (またはグループ) を検索し、選択ボックスをオンにします。
2. 次に、表示された一覧から、前のセクションで作成したアプリ登録を見つけます。
3. [選択] をクリックします。
完了を選択します。

新しい接続が接続のリストに表示され、[接続済み]の状態が表示されます。資格情報プロバイダー用に別の接続を作成する場合は、前述の手順を実行します。

ヒント

ポータルを使用して、資格情報プロバイダーへの接続をいつでも追加、更新、または削除できます。詳細については、「複数の接続の構成」を参照してください。

手順 5: Microsoft Entra ID アクセストークンを取得する

バックエンド API へのユーザー委任アクセスを有効にするには、委任されたユーザーまたはグループのアクセストークンが実行時に get-authorization-context ポリシーで提供される必要があります。通常、これはクライアントアプリのプログラムから Microsoft Authentication Library (MSAL) を使用して行われます。このセクションでは、テスト用のアクセストークンを手動で作成する手順を説明します。

ブラウザーに次の URL を貼り付けます。ただし、<tenant-id> と <client-id> の箇所は Microsoft Entra アプリ登録の値に置き換えます。

https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234`

プロンプトが表示されたら、サインインします。応答本文で、提供された code の値をコピーします (例: "0.AXYAh2yl…")。
次の POST 要求をトークンエンドポイントに送信します。ただし、<tenant-id> の箇所はテナント ID に置き換え、アプリ登録から取得したヘッダーおよび本文のパラメーターと、前の手順でコピーしたコードを含めます。
```
POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1
```
ヘッダー

Content-Type: application/x-www-form-urlencoded

本文
```
grant_type: "authorization_code"
client_id: <client-id>
client_secret: <client-secret>
redirect_uri: <redirect-url> 
code: <code>   ## The code you copied in the previous step
```
応答本文で、提供された access_token の値をコピーします (例: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...)。この値は、次の手順でポリシーを構成する際に必要になります。

手順 6: バックエンド API の get-authorization-context ポリシーを構成する

ユーザーまたはグループの代理でアクセスするバックエンド API の get-authorization-context ポリシーを構成します。テストのために、前のセクションで取得したユーザーの Microsoft Entra ID アクセストークンを使用してポリシーを構成できます。

portal にサインインし、API Management インスタンスに移動します。
左側のメニューから [API] を選択し、使用する OAuth 2.0 バックエンド API を選択します。
[すべての操作] を選択します。 [受信処理] セクションで、(</>) (コードエディター) アイコンを選択します。

inbound セクション内に get-authorization-context ポリシーを構成し、以下のように identity-type を jwt に設定します。

<policies>
    <inbound>
        [...]
        <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
        [...]
    </inbound> 
</policies>

上のポリシー定義に含まれるプレースホルダーを以下のように置き換えます。

<credential-provider-id> と <connection-id> の箇所には、前の手順で構成した資格情報プロバイダーの名前と接続の名前を設定します。
<access-token> の箇所には、前の手順で生成した Microsoft Entra ID アクセストークンを設定します。

手順 7: API をテストする

[テスト] タブで、構成した操作を 1 つ選択します。
[Send] を選択します。

応答が成功すると、バックエンド API からユーザーデータが返されます。

認証と承認ポリシーの詳細情報
Microsoft Entra ID でのスコープとアクセス許可の詳細を参照してください。