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

このページは Apigee と Apigee ハイブリッドに適用されます。

Apigee Edge ドキュメントを表示する

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

このトピックについて

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

ユースケース

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

ロール

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

  • クライアント アプリ - ユーザーの保護されたリソースにアクセスする必要があるアプリ。このフローでは通常、アプリはユーザーのノートパソコンなどのデバイス上でローカルに稼働するのではなく、サーバー上で稼働します。
  • Apigee - このフローでは、Apigee は OAuth 承認サーバーです。そのロールは、アクセス トークンを生成および検証し、保護されたリソースに対する承認済みリクエストをリソース サーバーに渡すことです。
  • リソース サーバー - 保護されたデータ（クライアント アプリがアクセスするには許可が必要なデータ）を格納するバックエンド サービス。Apigee でホストされている API プロキシを保護している場合、Apigee はリソース サーバーでもあります。

コードサンプル

GitHub 上で、稼働する状態の完全なクライアント認証情報権限付与タイプの実装例を確認できます。その他の例については、後述のその他のリソースをご覧ください。

フロー図

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

クライアント認証情報フロー

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

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

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

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

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

例:

curl -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

クライアント認証情報の付与タイプを使用するもご覧ください。

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

API 呼び出しは /oauth/token エンドポイントに送信されることに留意してください。このエンドポイントには、アプリの認証情報を検証するポリシーが接続されています。つまり、送信されたキーと、アプリの登録時に Apigee で作成されたキーとがポリシーによって比較されます。Apigee での OAuth エンドポイントに関する詳細は、OAuth エンドポイントとポリシーの構成をご覧ください。

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

認証情報に問題がない場合、Apigee からクライアントにアクセス トークンが返されます。問題がある場合はエラーが返されます。

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

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

フローとポリシーを構成する

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

カスタムフローの構成

API プロキシのフローの構成を説明する最も簡単な方法は、XML フローの定義を示すことです。以下は、アクセス トークン リクエストの処理を目的とした API プロキシのフローの例を示したものです。たとえば、リクエストが届き、パスのサフィックスが /oauth/token と一致すると、GetAccessToken ポリシーがトリガーされます。このようなカスタムフローの作成に必要な手順の概要については、OAuth エンドポイントとポリシーの構成をご覧ください。

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

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

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

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

このポリシーは、/oauth/token パスに接続されています。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 ポリシーを追加する必要があります。このポリシーでは、受信リクエストに有効なアクセス トークンがあるかどうかがチェックされます。トークンが有効な場合、Apigee はリクエストを処理します。トークンが有効ではない場合、Apigee はエラーを返します。基本的な手順については、アクセス トークンの検証をご覧ください。

<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 ポリシーを構成する方法について多数の例を紹介しています。