OAuth 2.0 ユーザー承認を構成して開発者ポータルのテスト コンソールを承認する方法

適用対象: 開発者 | Basic | Basic v2 | Standard | Standard v2 | Premium

多くの API では、OAuth 2.0 がサポートされています。OAuth 2.0 を使用すると、API をセキュリティで保護して、有効なユーザーのみにアクセスが許可されること、および有効なユーザーが許可されたリソースのみにアクセスできることを保証できます。 Azure API Management の対話型開発者コンソールとこのような API を使用するために、サービスで OAuth 2.0 ユーザー承認用の外部プロバイダーを構成できます。

開発者ポータルのテスト コンソールで OAuth 2.0 ユーザー認可を構成すると、開発者は OAuth 2.0 アクセス トークンを簡単に取得できます。 テスト コンソールから、API 呼び出しを使用してバックエンドにトークンを渡します。 トークンの検証は、JWT 検証ポリシーを使用するか、バックエンド サービスで個別に構成する必要があります。

前提条件

この記事では、開発者ポータルのテスト コンソールで OAuth 2.0 承認を使用するように API Management サービス インスタンスを構成する方法について説明しますが、OAuth 2.0 プロバイダーを構成する方法については説明しません。

API Management サービス インスタンスをまだ作成していない場合は、API Management サービス インスタンスの作成に関するページを参照してください。

シナリオの概要

API Management で OAuth 2.0 ユーザー承認を構成して、開発者ポータルのテスト コンソール (および Azure portal のテスト コンソール) がクライアントとして承認サーバーからトークンを取得できるようにします。 手順は似ていて、API Management サービス インスタンスでの OAuth 2.0 の構成に使用される必要な情報は同じですが、各 OAuth 2.0 プロバイダーの構成は異なります。 この記事では、OAuth 2.0 プロバイダーとして Microsoft Entra ID を使う例を示します。

構成手順の概要を次に示します。

1. API を表すためにアプリケーション (バックエンドアプリ) を Microsoft Entra ID に登録します。

2. API を呼び出す必要があるクライアント アプリケーションとなる、別のアプリケーション (クライアントアプリ) を Microsoft Entra ID に登録します (この場合は、開発者ポータルのテスト コンソール)。

   Microsoft Entra ID で、このクライアントアプリでこのバックエンドアプリを呼び出せるように、アクセス許可を付与します。

3. OAuth 2.0 ユーザー承認を使用して API を呼び出すように開発者ポータルのテスト コンソールを構成します。

4. OAuth 2.0 ユーザー承認を使用するように API を構成します。

5. すべての着信要求の OAuth 2.0 トークンを事前承認するポリシーを追加します。 すべての OAuth 2.0 プロバイダーに対して validate-jwt ポリシーを使用できます。

この構成では、次の OAuth フローがサポートされています。

1. 開発者ポータルで、クライアントアプリの資格情報を使って Microsoft Entra ID からのトークンが要求されます。

2. 検証に成功すると、Microsoft Entra ID でアクセスまたは更新トークンが発行されます。

3. 開発者 (開発者ポータルのユーザー) が、Authorization ヘッダーを使用して API 呼び出しを行います。

4. このトークンが、Microsoft Entra ID で API Management の validate-jwt ポリシーを使って検証されます。

5. 検証結果に基づいて、開発者が開発者ポータルで応答を受け取ります。

認可付与タイプ

Azure API Management では、次の OAuth 2.0 付与タイプ (フロー) がサポートされています。 付与タイプとは、クライアント アプリケーション (このコンテキストでは、開発者ポータルのテスト コンソール) でバックエンド API へのアクセス トークンを取得する方法を指します。 OAuth 2.0 プロバイダーとシナリオに応じて、1 つまたは複数の付与タイプを構成できます。

概要を以下に示します。 付与タイプの詳細については、「OAuth 2.0 Authorization Framework」と「OAuth 付与タイプ」を参照してください。

セキュリティの考慮事項

付与タイプでトークンがどのように生成されるかや、トークンのスコープ、またトークンをどのように公開できるかについて考慮してください。 悪意のあるアクターは、侵害されたトークンを使用して、トークンのスコープ内の他のリソースにアクセスできます。

開発者ポータルのテスト コンソールで OAuth 2.0 ユーザー認可を構成する場合:

• 開発者が API をテストするために必要なトークンのスコープを最低限に抑えます。 テスト コンソール、または影響を受ける API にスコープを制限します。 トークン スコープを構成する手順は、OAuth 2.0 プロバイダーによって異なります。

  シナリオによっては、バックエンド API にアクセスするために作成する他のクライアント アプリケーションに対して、より制限の厳しいまたは緩いトークン スコープを構成することができます。

• クライアント資格情報フローを有効にする場合は、十分注意してください。 クライアント資格情報フローを使用する際に、開発者ポータルのテスト コンソールでは資格情報は求められません。 開発者コンソールの開発者や匿名ユーザーにアクセス トークンが誤って公開される可能性があります。

キー情報を追跡する

このチュートリアルでは、後で参照するキー情報を記録するように求められます。

• バックエンド アプリケーション (クライアント) ID: バックエンド API を表すアプリケーションの GUID
• バックエンド アプリケーション スコープ: API にアクセスするために作成できる 1 つ以上のスコープ。 スコープ形式は、api://<Backend Application (client) ID>/<Scope Name> (api://1764e900-1827-4a0b-9182-b2c1841864c2/Read など) です
• クライアント アプリケーション (クライアント) ID: 開発者ポータルを表すアプリケーションの GUID
• クライアント アプリケーションのシークレット値: Microsoft Entra ID でクライアント アプリケーションと対話するためのシークレットの役割を果たす GUID

OAuth サーバーにアプリケーションを登録する

OAuth 2.0 プロバイダーに 2 つのアプリケーションを登録する必要があります。1 つは保護するバックエンド API を表し、もう 1 つは API を呼び出すクライアント アプリケーション (この場合、開発者ポータルのテスト コンソール) を表します。

OAuth 2.0 プロバイダーとして Microsoft Entra ID を使う手順の例を次に示します。 アプリの登録の詳細については、次を参照してください。「クイックスタート:Web API を公開するようにアプリケーションを構成する」。

API を表すために Microsoft Entra ID にアプリケーションを登録する

1. Azure portal で、 [アプリの登録] を検索して選択します。

2. [新規登録] を選択します。

3. [アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。

   • [名前] セクションに、アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します (例: backend-app)。
   • [サポートされているアカウントの種類] セクションで、シナリオに適したオプションを選択します。

4. [リダイレクト URI] セクションは空のままにします。 後で、API Management の OAuth 2.0 構成で生成されたリダイレクト URI を追加します。

5. [登録] を選択して、アプリケーションを作成します。

6. アプリの [概要] ページで、 [アプリケーション (クライアント) ID] の値を見つけ、後で使用するために記録します。

7. サイド メニューの [管理] セクションで、 [API の公開] を選択し、 [アプリケーション ID URI] を既定値に設定します。 この値は、後で使用するために記録しておきます。

8. [スコープの追加] ボタンを選択して、 [スコープの追加] ページを表示します。

   1. API でサポートされているスコープのスコープ 名 (Files.Read など) を入力します。
   2. [同意できるのはだれですか?] で、[管理者とユーザー] など、シナリオ用の選択を行います。 より高い特権のシナリオの場合は、[管理者のみ] を選択します。
   3. [管理者の同意の表示名] と [管理者の同意の説明] を入力します。
   4. [有効] のスコープ状態が選択されていることを確認します。

9. [Scope の追加] ボタンを選択してスコープを作成します。

10. 前の 2 つの手順を繰り返して、API でサポートされているすべてのスコープを追加します。

11. スコープが作成されたら、以降の手順で使用するためにそれらを書き留めておきます。

クライアント アプリケーションとなる別のアプリケーションを Microsoft Entra ID tに登録する

API を呼び出すすべてのクライアント アプリケーションを Microsoft Entra ID にアプリケーションとして登録します。

1. Azure portal で、 [アプリの登録] を検索して選択します。

2. [新規登録] を選択します。

3. [アプリケーションの登録] ページが表示されたら、以下のアプリケーションの登録情報を入力します。

   • [名前] セクションに、アプリのユーザーに表示されるわかりやすいアプリケーション名を入力します (例: client-app)。
   • [サポートされているアカウントの種類] セクションで、シナリオに適したオプションを選択します。

4. [リダイレクト URI] セクションで、[Web] を選択し、[URL] フィールドは今は空のままにします。

5. [登録] を選択して、アプリケーションを作成します。

6. アプリの [概要] ページで、 [アプリケーション (クライアント) ID] の値を見つけ、後で使用するために記録します。

7. 以降の手順で使用するこのアプリケーションのクライアント シークレットを作成します。

   1. サイド メニューの [管理] セクションで、[証明書とシークレット] を選択します。
   2. [クライアント シークレット] で、 [+ 新しいクライアント シークレット] を選択します。
   3. [クライアント シークレットの追加] で、 [説明] を指定し、キーの有効期限がいつ切れるようにするかを選択します。
   4. [追加] を選択します。

シークレットが作成されたら、後の手順で使用するために、そのキー値を書き留めておきます。 ポータルでシークレットに再びアクセスすることはできません。

Microsoft Entra ID でアクセス許可を付与する

API とテスト コンソールを表す 2 つのアプリケーションを登録したら、クライアント アプリがバックエンド アプリを呼び出すことができるようにアクセス許可を付与します。

1. Azure portal で、 [アプリの登録] を検索して選択します。

2. 対象のクライアント アプリを選択します。 次に、サイド メニューで [API のアクセス許可] を選択します。

3. [+ アクセス許可の追加] を選択します。

4. [API を選択します] の下で、 [自分の API] を選択し、バックエンド アプリを検索して選択します。

5. [委任されたアクセス許可] を選択してから、バックエンド アプリへの適切なアクセス許可を選択します。

6. [アクセス許可の追加] を選択します.

省略可能:

1. クライアント アプリの [API のアクセス許可] ページに移動します。

2. [<お使いのテナント名> に管理者の同意を与えます] を選択して、このディレクトリ内のすべてのユーザーに代わって同意を付与します。

API Management で OAuth 2.0 承認サーバーを構成する

1. Azure portal で、API Management インスタンスに移動します。

2. サイド メニューの [開発者ポータル] で、[OAuth 2.0 + OpenID Connect] を選択します。

3. [OAuth 2.0] タブで、[+ 追加] を選択します。

   

4. [名前] フィールドと [説明] フィールドに、名前とオプションの説明を入力します。

   Note

   これらのフィールドでは、現在の API Management サービス内で OAuth 2.0 認可サーバーが識別されます。 これらの値は、OAuth 2.0 サーバーからのものではありません。

5. [クライアント登録ページの URL] (https://contoso.com/login など) を入力します。 OAuth 2.0 プロバイダーでアカウントのユーザー管理がサポートされている場合、ユーザーはこのページで自分のアカウントを作成および管理できます。 このページは、使用される OAuth 2.0 プロバイダーによって異なります。

   OAuth 2.0 プロバイダーでユーザーによるアカウント管理が構成されていない場合は、会社の URL、http://localhost のような URL など、プレースホルダー URL をここで入力してください。

   

6. フォームの次のセクションには、 [承認許可の種類] 、 [承認エンドポイントの URL] 、および [承認要求方法] の設定が含まれます。

   • 必要な承認許可の種類を 1 つ以上選択します。 この例では、[Authorization code] (承認コード) (既定値) を選択します。 詳細情報

   • [Authorization endpoint URL (認証エンドポイント URL)] を入力します。 エンドポイント URL は、いずれかのアプリ登録の [エンドポイント] ページから取得できます。 Microsoft Entra ID でのシングルテナント アプリの場合、これは次の URL のどちらかのようになります。ここでの {aad-tenant} は、Microsoft Entra テナントの ID に置き換えてください。

     v2 エンドポイントの使用をお勧めします。ただし、API Management では v1 エンドポイントと v2 エンドポイントの両方がサポートされています。

     https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)

     https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)

   • [認証要求方式 (Authorization request method)] は、認証要求が OAuth 2.0 サーバーに送信される方法を指定します。 [POST] を選択します。

   

7. [トークン エンドポイントの URL]、[クライアント認証方法]、[アクセス トークンの送信方法]、および [既定のスコープ] を指定します。

   • [トークン エンドポイントの URL] を入力します。 Microsoft Entra ID でのシングルテナント アプリの場合、これは次の URL のどちらかのようになります。ここでの {aad-tenant} は、Microsoft Entra テナントの ID に置き換えてください。 前に選択した同じエンドポイント バージョン (v2 または v1) を使用してください。

     https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)

     https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)

   • v1 エンドポイントを使用する場合、次の本文パラメーターを追加します:
     * 名前: resource。
     * 値: バックエンド アプリのアプリケーション (クライアント) ID。

   • v2 エンドポイントを使用する場合:
     * "既定のスコープ" フィールドで作成したバックエンド アプリ スコープを入力します。
     * バックエンド アプリとクライアント アプリの両方の登録のためのアプリケーション マニフェストで、accessTokenAcceptedVersion プロパティの値を 2 に設定します。

   • [クライアント認証方法] と [アクセス トークンの送信方法] では、既定の設定をそのまま使用します。

8. [クライアントの資格情報] で、[クライアント ID] と [クライアント シークレット] を入力します。これらは、クライアント アプリの作成と構成のプロセスで取得しました。

9. [クライアント ID] と [クライアント シークレット] を指定すると、承認コードのリダイレクト URI が生成されます。 この URI は、OAuth 2.0 サーバー構成でリダイレクト URI を構成するために使用します。

   開発者ポータルでは、URI サフィックスは次の形式になります。

   • 承認コード付与フローの場合は /signin-oauth/code/callback/{authServerName}
   • 暗黙的な許可のフローの場合は /signin-oauth/implicit/callback

   

   クライアント アプリ登録の [認証] ページに、適切なリダイレクト URI をコピーします。 アプリの登録で、[認証]>[+ プラットフォームの追加]>[Web] を選択し、リダイレクト URI を入力します。

10. [承認許可の種類] を [リソース所有者のパスワード] に設定した場合は、 [リソース所有者のパスワード資格情報] セクションを使用してそれらの資格情報を指定します。それ以外の場合は、空白のままにすることができます。

11. [作成] を選択して、API Management OAuth 2.0 認可サーバーの構成を保存します。

12. 開発者ポータルを再発行します。

    重要

    OAuth 2.0 に関連する変更を加える場合は、関連のある変更点 (スコープ変更など) として変更を加えるたびに、改めて開発者ポータルを公開してください。そうしないと、それがそのポータルに反映されず、その後 API を使ってみても変化はありません。

OAuth 2.0 ユーザー承認を使用するように API を構成する

OAuth 2.0 サーバーの構成を保存した後、この構成を使用するように API を構成します。

1. 左側の [API Management] メニューから、[API] を選択します。

2. 目的の API の名前を選び、[設定] タブを選択します。[セキュリティ] セクションまでスクロールしてから、[OAuth 2.0] を選択します。

3. ドロップダウン リストから目的の認可サーバーを選び、[保存] を選択します。

   

開発者ポータル - OAuth 2.0 ユーザー認可をテストする

OAuth 2.0 認可サーバーを構成して、そのサーバーを使用するように API を構成したら、開発者ポータルに移動して API を呼び出すことにより、それをテストできます。

1. Azure API Management インスタンスの [概要] ページで、上部のメニューの [開発者ポータル] を選択します。

2. 開発者ポータルで API の下にある任意の操作を参照します。

3. [試してみる] を選択すると、開発者コンソールが表示されます。

4. [承認] セクションの新しい項目は、先ほど追加した承認サーバーに対応しています。

5. 認可ドロップダウン リストから [認可コード] を選択します。

   

6. メッセージが表示されたら、Microsoft Entra テナントにサインインします。

   • 既にアカウントにサインインしている場合は、求められない可能性があります。

7. サインインに成功すると、Microsoft Entra ID アクセス トークンを使用する要求に Authorization ヘッダーが追加されます。 以下は、省略されたサンプル トークン (Base64 エンコード) です。

   Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
   

8. 残りのパラメーターに必要な値を構成し、[送信] を選択して API を呼び出します。

要求を事前承認する JWT 検証ポリシーを構成する

ここまでの構成で、API Management はアクセス トークンを検証していません。 承認ヘッダー内のトークンをバックエンド API に渡しただけです。

要求を事前承認するには、各着信要求のアクセス トークンを検証するように validate-jwt ポリシーを構成します。 要求に有効なトークンがない場合、API Management はそれをブロックします。

次のポリシーの例では、<inbound> ポリシー セクションへの追加時に、Authorization ヘッダーで示される Microsoft Entra ID から取得されたアクセス トークン内の対象ユーザーのクレーム値を確認します。 トークンが有効ではない場合、エラー メッセージを返します。 シナリオに適したポリシー スコープでこのポリシーを構成します。

• openid-config URL では、aad-tenant は Microsoft Entra ID のテナント ID です。 この値は、Azure portal (Microsoft Entra リソースの [概要] ページなど) で見つけます。 ここに示す例では、シングルテナントの Microsoft Entra アプリと v2 構成エンドポイントを想定しています。
• claim の値は、Microsoft Entra IDに登録したバックエンド アプリのクライアント ID です。

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

ポリシーの構成方法については、ポリシーの設定と編集に関する記事をご覧ください。 JWT 検証に関するその他のカスタマイズについては、validate-jwt リファレンスを参照してください。 Microsoft Entra サービスによって提供された JWT を検証するために、API Management でも validate-azure-ad-token ポリシーが提供されます。

次のステップ

OAuth 2.0 と API Management の使用について詳しくは、「OAuth 2.0 承認と Microsoft Entra ID を使用して Azure API Management で API を保護する」をご覧ください。