クライアント認証情報の権限付与タイプの実装

クライアント認証情報の権限付与タイプでは、アプリはそれ自体の認証情報(クライアント ID とクライアント シークレット)を、アクセス トークンを生成するように設定されている Apigee Edge のエンドポイントに送信します。認証情報が有効である場合は、Edge によってクライアント アプリにアクセス トークンが返されます。

このトピックについて

このトピックでは、OAuth 2.0 のクライアント認証情報の権限付与タイプについて、全般的な説明を示し、Apigee Edge でこのフローを実装する方法を説明します。

使用例

通常、この権限付与タイプは、アプリがリソース オーナーでもある場合に使用されます。たとえば、アプリの動作に必要なデータを保存および取得するために、アプリがエンドユーザーが所有するデータではなく、バックエンドのクラウドベースのストレージ サービスにアクセスする必要があることが考えられます。この権限付与タイプのフローは、厳密に、クライアント アプリと認可サーバーの間で発生します。この権限付与タイプのフローにはエンドユーザーは関与しません。

役割

役割により、OAuth のフローに関与する「アクター」が指定されます。Apigee Edge の位置付けの説明の一助として、クライアント認証情報の役割の概要について簡単に説明します。OAuth 2.0 の役割について詳しくは IETF OAuth 2.0 仕様をご覧ください。

  • クライアント アプリ -- ユーザーの保護されたリソースにアクセスする必要があるアプリ。通常、このフローでは、アプリはユーザーのノートパソコン上やデバイス上でローカルに実行されるのではなく、サーバー上で実行されます。
  • Apigee Edge -- このフローでは、Apigee Edge は OAuth 認可サーバーです。その役割は、アクセス トークンを生成し、アクセス トークンを検証し、保護されたリソースに対する認可済みリクエストをリソース サーバーに渡すことです。
  • リソース サーバー -- クライアント アプリからのアクセスにはアクセス権限が必要な、保護されたデータを保存するバックエンド サービスです。Apigee Edge でホストされている API プロキシを保護している場合、Apigee Edge はリソース サーバーでもあります。

コードサンプル

クライアント認証情報の権限付与タイプの完全で実用的なサンプル実装が GitHub にあります。その他の例へのリンクについては参考情報をご覧ください。

フロー図

次のフロー図は、Apigee Edge が認可サーバーとして機能する、クライアント認証情報の権限付与タイプのフローを示しています。このフローでは、通常、Edge はリソース サーバーでもあります。つまり、API プロキシが、保護されたリソースとなります。


クライアント認証情報のフローでのステップ

Apigee Edge が認可サーバーの役割を果たす、クライアント認証情報の権限付与タイプの実装するために必要なステップの概要を以下に示します。このフローでは、クライアント アプリはそれ自体のクライアント ID とクライアント シークレットを提示するのみで、それらが有効である場合は、Apigee Edge によってアクセス トークンが返されます。

前提条件: クライアント アプリを Apigee Edge に登録し、クライアント ID とクライアント シークレット キーを取得している必要があります。詳しくはクライアント アプリの登録をご覧ください。

1. クライアントがアクセス トークンをリクエストする

アクセス トークンを受け取るために、クライアントは、登録済みのデベロッパー アプリから取得したクライアント ID とクライアント シークレットの値を使用して、Edge への API 呼び出しを POST します。また、パラメータ grant_type=client_credentials はクエリ パラメータとして渡される必要があります(ただし、リクエストのヘッダー内または本文内のこのパラメータを受け入れるように、OAuthV2 ポリシーを構成できます。詳しくは OAuthV2 ポリシーをご覧ください)。

例:

    $ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'
    

注: 上記のように、client_id と client_secret の値をクエリ パラメータとして渡すことができますが、それらを Authorization ヘッダー内の Base64 URL エンコード文字列として渡すことをおすすめします。そうするには、Base64 エンコード ツールまたはユーティリティを使用して、2 つの値をコロンで区切ってまとめてエンコードする必要があります。aBase64EncodeFunction(clientidvalue:clientsecret) のようにします。そうすると、上記の例は次のようにエンコードされます。

result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // 2 つの値はコロンで区切られています

この文字列を Base64 エンコードすると、bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg== となります。

次のようにして、トークン リクエストを作成します。

    $ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='
    

2. Edge が認証情報を検証する

API 呼び出しは /accesstoken エンドポイントに送信されていることに注意してください。このエンドポイントには、アプリの認証情報を検証するポリシーがアタッチされています。したがって、送信されたキーとアプリが登録されたときに Apigee Edge が作成したキーを、そのポリシーを用いて比較します。Edge での OAuth エンドポイントについて詳しくは、OAuth エンドポイントとポリシーの構成をご覧ください。

3. Edge がレスポンスを返す

認証情報が有効である場合は、Edge によってクライアントにアクセス トークンが返されます。そうでない場合は、エラーが返されます。

4. 保護された API をクライアントが呼び出す

これでクライアントは、有効なアクセス トークンを使用することで保護された API を呼び出せるようになりました。このシナリオでは、Apigee Edge(プロキシ)に対してリクエストが行われ、Edge はターゲット リソース サーバーに API 呼び出しを渡す前にアクセス トークンを検証する責任を担います。例については、後述の保護された API の呼び出しをご覧ください。

フローとポリシーの構成

認可サーバーである Edge はアクセス トークンに対するリクエストを処理します。API デベロッパーは、カスタムフローを使用して、トークン リクエストを処理し、OAuthV2 ポリシーを追加して構成するためのプロキシを作成する必要があります。このセクションでは、そのエンドポイントを構成する方法について説明します。

カスタムフロー構成

API プロキシのフローがどのように構成されるかを示す最も簡単な方法は、XML フロー定義を示すことです。アクセス トークン リクエストを処理するように設計されている API プロキシのフローの例を次に示します。この例では、リクエストを受信し、そのパスのサフィックスが /accesstoken と一致すると、GetAccessToken ポリシーがトリガーされます。このようなカスタムフローを作成するために必要なステップの概要については、OAuth エンドポイントとポリシーの構成をご覧ください。

    <Flows>
      <Flow name="GetAccessToken">
             <!-- This policy flow is triggered when the URI path suffix
             matches /oauth/accesstoken. Publish this URL to app developers
             to use when obtaining an access token using an auth code
             -->
        <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
        <Request>
            <Step><Name>GetAccessToken</Name></Step>
        </Request>
      </Flow>
    </Flows>
    

ポリシーを使用してフローを構成する

以下のようにして、エンドポイントにポリシーをアタッチする必要があります。プロキシ エンドポイントに OAuthV2 ポリシーを追加するために必要なステップの概要については、OAuth エンドポイントとポリシーの構成をご覧ください。

アクセス トークンを取得する

このポリシーは /accesstoken パスにアタッチされています。GenerateAccessToken オペレーションが指定されている OAuthV2 ポリシーが使用されています。

    <OAuthV2 name="GetAccessToken">
      <Operation>GenerateAccessToken</Operation>
      <ExpiresIn>3600000</ExpiresIn>
      <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
      </SupportedGrantTypes>
      <GenerateResponse/>
    </OAuthV2>
    

アクセス トークンを取得するための API 呼び出しは POST となり、Base64 エンコードされた client_id と client_secret、およびクエリ パラメータ grant_type=client_credentials を持つ Authorization ヘッダーが含まれています。スコープとステートのオプションのパラメータを含めることもできます。次に例を示します。

    $ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'
    

アクセス トークン検証ポリシーのアタッチ

OAuth 2.0 のセキュリティで API を保護するには、VerifyAccessToken オペレーションを持つ OAuthV2 ポリシーを追加する必要があります。このポリシーでは、受信リクエストに有効なアクセス トークンがあるかどうかがチェックされます。トークンが有効である場合は Edge によってリクエストが処理されます。有効でない場合は Edge によってエラーが返されます。基本的なステップについてはアクセス トークンの検証をご覧ください。

    <OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
        <DisplayName>VerifyAccessToken</DisplayName>
        <ExternalAuthorization>false</ExternalAuthorization>
        <Operation>VerifyAccessToken</Operation>
        <SupportedGrantTypes/>
        <GenerateResponse enabled="true"/>
        <Tokens/>
    </OAuthV2>
    

保護された API の呼び出し

OAuth 2.0 のセキュリティで保護された API を呼び出すには、有効なアクセス トークンを提示する必要があります。適切なパターンは、次のように Authorization ヘッダーにトークンを含めることです。アクセス トークンは「署名なしトークン」とも呼ばれます。

    $ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
      http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282
    

アクセス トークンの送信もご覧ください。

参考情報

  • Apigee が提供する API デベロッパー向けのオフライン トレーニングには、OAuth を含む API セキュリティに関するコースがあります。
  • OAuthV2 ポリシー -- 認可サーバーにリクエストを行う方法や OAuthV2 ポリシーを構成する方法に関する多数の例が示されています。