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

クライアント認証情報の権限付与タイプでは、アプリはそれ自体の認証情報(クライアント 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 ポリシーを構成する方法に関する多数の例が示されています。