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

クライアント認証情報の権限付与タイプでは、アプリはそれ自体の認証情報（クライアント 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 によってアクセストークンが返されます。

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

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 では、OAuth を含む API セキュリティに関するコースなど、API デベロッパー向けのオンライントレーニングを実施しています。
OAuthV2 ポリシー -- 認可サーバーにリクエストを行う方法や OAuthV2 ポリシーを構成する方法に関する多数の例が示されています。