OAuth2 スコープの操作

このページの内容は Apigee と Apigee ハイブリッドに該当します。

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

このトピックでは、Apigee で OAuth 2.0 スコープを使用および適用する方法について説明します。

OAuth2 スコープとは

OAuth 2.0 スコープで、アクセストークンに付与されるアクセス権の範囲を制限します。たとえば、クライアントアプリに発行するアクセストークンに保護されたリソースの読み取り / 書き込みアクセス権を付与するか、読み取りアクセス権だけを付与するかを制御できます。API を実装して、必要に応じてスコープまたはスコープの組み合わせを適用できます。つまり、クライアントが読み取りスコープのトークンを受信して、書き込みアクセス権が必要な API エンドポイントを呼び出そうとすると、呼び出しは失敗します。

このトピックでは、アクセストークンにスコープを割り当てる方法と、Apigee で OAuth 2.0 スコープを適用する方法について説明します。このトピックを読むと、自信を持ってスコープを使用できるようになります。

アクセストークンにスコープを割り当てる方法

Apigee はアクセストークンを生成する際に、そのトークンにスコープを割り当てることができます。割り当ての仕組みを理解するには、API プロダクト、デベロッパー、デベロッパーアプリという Apigee エンティティを理解する必要があります。概要については、公開の概要をご覧ください。先に進む前に、必要に応じてこの資料を確認することをおすすめします。

アクセストークンはランダムな文字からなる長い文字列です。これによって Apigee は受信 API リクエストを確認できます（一般的なユーザー名とパスワードのクレデンシャルの代わりになると考えることができます）。厳密には、トークンは次のようなメタデータのコレクションを参照するキーです。

{
  "issued_at" : "1416962591727",
  "application_name" : "0d3e1d41-a59f-4d74-957e-d4e3275d4781",
  "scope" : "A",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-bs0cSuqS9y]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-AdBmANhsag@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "eTtB7w5lvk3DnOZNGReBlvGvIAeAywun",
  "access_token" : "ODm47ris5AlEty8TDc1itwYPe5MW",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

トークンのメタデータには実際のアクセストークン文字列と有効期限情報、そのトークンに関連付けられたデベロッパーアプリ、デベロッパー、プロダクトを識別するものが含まれます。また、メタデータには「スコープ」も含まれます。

トークンにスコープを割り当てる仕組み

スコープを理解するには、まず、デベロッパーアプリ内の各プロダクトにゼロまたは複数のスコープが割り当てられることを覚えることが大事です。これらのスコープは、プロダクトの作成時に割り当てることも後から追加することもできます。スコープは名前のリストとして存在し、各プロダクトに関連付けられる「メタデータ」に含まれています。

デベロッパーアプリを作成してプロダクトを追加すると、Apigee はデベロッパーアプリ内のすべてのプロダクトを調べ、それらのプロダクトの全スコープのリスト（アプリのマスターリストまたはグローバルスコープリスト - 認識されたすべてのスコープをまとめたもの）を作成します。

クライアントアプリが Apigee にアクセストークンをリスエストする際は、トークンに関連付けるスコープも任意で指定できます。たとえば、以下のリクエストではスコープ「A」を関連付けるように要求しています。つまり、クライアントは認可サーバー（Apigee）に対してスコープ「A」を割り当てたアクセストークンを生成するよう要求しています（これにより、スコープ「A」が割り当てられた API を呼び出す権限がアプリに付与されます）。この場合、アプリは次のような POST リクエストを送信します。

curl -i -X POST -H Authorization: Basic Mg12YTk2UkEIyIBCrtro1QpIG \
  -H content-type:application/x-www-form-urlencoded \
  https://apitest.acme.com/oauth/token?grant_type=client_credentials&scope=A

挙動

Apigee はこのリクエストを受信すると、リクエストを作成したアプリや、クライアントが登録したデベロッパーアプリを把握します（クライアント ID とクライアントシークレットという 2 つのキーが基本認証ヘッダーにエンコードされています）。scope クエリパラメータが含まれているため、Apigee はデベロッパーアプリに関連付けられた API プロダクトのいずれかにスコープ「A」が設定されているかどうかを判断する必要があります。該当するプロダクトがある場合は、スコープ「A」を割り当てたアクセストークンが生成されます。別の観点から見ると、scope クエリパラメータはある種のフィルタになります。たとえば、デベロッパーアプリがスコープ「A」、「B」、「X」を認識する場合、クエリパラメータで「scope=X Y Z」が指定されていればスコープ「X」のみがトークンに割り当てられます。

注:

スコープパラメータの値が認識済みのスコープのいずれにも一致しない場合、トークンは生成されますが、そのトークンにスコープは付与されません（スコープのメタデータは空になります）。
使用できるスコープは、プロダクトで指定されているスコープのみです。デベロッパーアプリに関連付けられているどのプロダクトにもスコープが指定されていない場合、トークンを生成するための呼び出しでスコープをリクエストするだけでは、スコープが割り当てられたトークンを生成することはできません。スコープが割り当てられたトークンを生成できるのは、関連するデベロッパーアプリにリクエストするスコープを指定するプロダクトが含まれている場合のみです。

クライアントが scope パラメータを指定していない場合、Apigee はデベロッパーアプリで認識されたすべてのスコープを含むトークンを生成します。デフォルトの動作では、デベロッパーアプリに含まれるすべてのプロダクトのすべてのスコープを含むアクセストークンが返されるということを理解しておくことが重要です。

デベロッパーアプリに関連付けられているどのプロダクトにもスコープが指定されていないのにトークンにスコープが割り当てられている場合、そのトークンを使用した呼び出しは失敗します。

たとえば、デベロッパーアプリがスコープ A、B、C、D を認識するとします。これが、アプリのスコープのマスターリストです。アプリ内のあるプロダクトにスコープ A と B が割り当てられていて、別のプロダクトにスコープ C と D が割り当てられているといったように、任意の組み合わせでスコープが設定されています。クライアントが scope パラメータを指定していない場合（または値のない scope パラメータを指定している場合）、トークンには 4 つのスコープ（A、B、C、D）がすべて付与されます。この場合も、トークンはデベロッパーアプリによって認識されるすべてのスコープである一連のスコープを受け取ります。

デフォルトの動作によって、認識されているすべてのスコープが設定されたアクセストークンが返されるというケースがもう 1 つあります。それは GenerateAccessToken ポリシー（アクセストークンを生成する Apigee ポリシー）で <Scope> 要素が指定されていない場合です。たとえば、次の GenerateAccessToken ポリシーでは <Scope> が指定されています。その <Scope> 要素がない場合（または存在するが空の場合）、デフォルトの動作が実行されます。

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-GenerateAccessToken">
    <DisplayName>OAuthV2 - Generate Access Token</DisplayName>
    <Attributes>
      <Attribute name='hello' ref='system.time' display='false'>value1</Attribute>
    </Attributes>
    <Scope>request.queryparam.scope</Scope> 
    <GrantType>request.formparam.grant_type</GrantType>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
</OAuthV2>

スコープが適用される仕組み

まず、Apigee ではアクセストークンが OAuthV2 ポリシーで検証される点に留意してください（通常はプロキシフローの先頭に配置されます）。このポリシーでは VerifyAccessToken オペレーションが指定されている必要があります。このポリシーの内容を見てみましょう。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope> <!-- Optional: space-separated list of scope names. -->
    <GenerateResponse enabled="true"/>
</OAuthV2>

<Scope> 要素に注目してください。この要素を使用して、ポリシーが受け入れるスコープを指定します。

この例では、アクセストークンにスコープ「A」が含まれていればポリシーは成功します。この <Scope> 要素が省略されている場合や値がない場合、ポリシーはアクセストークンのスコープを無視します。

スコープに基づいてアクセストークンを検証する機能を使用し、特定のスコープを適用するように API を設計できます。そのためには、スコープ対応の VerifyAccessToken ポリシーをアタッチしてカスタムフローを作成します。

API にエンドポイント /resourceA のフローが定義されているとします。

<Flow name="resourceA">
            <Condition>(proxy.pathsuffix MatchesPath "/resourceA") and (request.verb = "GET")</Condition>
            <Description>Get a resource A</Description>
            <Request>
                <Step>
                    <Name>OAuthV2-VerifyAccessTokenA</Name>
                </Step>
            </Request>
            <Response>
                <Step>
                    <Name>AssignMessage-CreateResponse</Name>
                </Step>
            </Response>
        </Flow>

このフローがトリガーされると（リクエストのパスサフィックスに /resourceA が含まれる場合）、OAuthV2-VerifyAccessTokenA ポリシーがすぐに呼び出されます。このポリシーは、アクセストークンが有効であることを確認すると、トークンがサポートしているスコープを調べます。次のように <Scope>A</Scope> を設定してポリシーが構成されている場合、アクセストークンにスコープ「A」が割り当てられている場合にのみポリシーが成功します。それ以外の場合はエラーが返されます。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

まとめると、API デベロッパーは API にスコープが適用されるように設計する必要があります。そのためには、デベロッパーが特定のスコープを処理するカスタムフローを作成し、スコープを適用する VerifyAccessToken ポリシーをアタッチする必要があります。

コードの例

最後に、トークンにスコープが割り当てられて、スコープが適用される仕組みを説明する API 呼び出しの例を見ていきましょう。

デフォルトの場合

デベロッパーアプリに複数のプロダクトが含まれていて、それらのプロダクトのスコープが A、B、C だとします。この API 呼び出しはアクセストークンをリクエストしますが、scope クエリパラメータは指定されていません。

curl -X POST -H content-type:application/x-www-form-urlencoded \
  https://apitest.acme.com/scopecheck1/token?grant_type=client_credentials

この場合、生成されるトークンにはスコープ A、B、C が割り当てられます（デフォルトの動作）。このトークンのメタデータは次のような内容になります。

{
  "issued_at" : "1417016208588",
  "application_name" : "eb1a0333-5775-4116-9eb2-c36075ddc360",
  "scope" : "A B C",
  "status" : "approved",
  "api_product_list" : "[scopecheck1-yEgQbQqjRR]",
  "expires_in" : "1799", //--in seconds
  "developer.email" : "scopecheck1-yxiuHuZcDW@apigee.com",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "atGFvl3jgA0pJd05rXKHeNAC69naDmpW",
  "access_token" : "MveXpj4UYXol38thNoJYIa8fBGlI",
  "organization_name" : "wwitman",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

ここで、API エンドポイントにスコープ「A」が設定されているとします（つまり、VerifyAccessToken にスコープ「A」が含まれている必要があります）。VerifyAccessToken ポリシーの内容は次のとおりです。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenA">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

たとえば、スコープ A を適用するエンドポイントを次のように呼び出すとします。

curl -X GET -H Authorization: Bearer MveXpj4UYXol38thNoJYIa8fBGlI \
  https://apitest.acme.com/scopecheck1/resourceA

この GET 呼び出しは成功します。

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

エンドポイントが呼び出されるとトリガーされる VerifyAccessToken ポリシーにスコープ A が必要ですが、アクセストークンにはデフォルトの動作でスコープ A、B、C が付与されているからです。

フィルタリングする場合

スコープが A、B、C、X が設定されたプロダクトを含むデベロッパーアプリがあるとします。アクセストークンをリクエストし、次のように scope クエリパラメータを含めます。

curl -i -X POST -H content-type:application/x-www-form-urlencoded \
  'https://apitest.acme.com/oauth/token?grant_type=client_credentials&scope=A X'

この場合、生成されるトークンにはスコープ A と X が割り当てられます。これは、A と X の両方が有効なスコープだからです。デベロッパーアプリはスコープ A、B、C、X を認識することを思い出してください。上記の例では、これらのスコープに基づいて API プロダクトのリストをフィルタリングしています。プロダクトにスコープ A または X が設定されている場合、これらのスコープを適用する API エンドポイントを構成できます。プロダクトにスコープ A も X も設定されていなければ（たとえば B、C、Z が設定されている場合）、スコープ A または X を適用する API をこのトークンで呼び出すことはできません。

次のように、新しいトークンを使用して API を呼び出すとします。

curl -X GET -H Authorization: Bearer Rkmqo2UkEIyIBCrtro1QpIG \
  https://apitest.acme.com/scopecheck1/resourceX

アクセストークンが API プロキシで検証されます。次に例を示します。

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuthV2-VerifyAccessTokenX">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <Scope>A X</Scope>
    <GenerateResponse enabled="true"/>
</OAuthV2>

GET 呼び出しトリガーが成功して、レスポンスを返します。次に例を示します。

 {
   "hello" : "Tue, 25 Nov 2014 01:35:53 UTC"
 }

VerifyAccessToken ポリシーにスコープ A または X が必要で、アクセストークンにスコープ A と X が含まれているため、この呼び出しは成功します。もちろん、<Scope> 要素が「B」に設定されていた場合、この呼び出しは失敗します。

まとめ

Apigee が OAuth 2.0 スコープを処理する仕組みを理解しておくことは重要です。以下に重要な点をまとめます。

デベロッパーアプリは、すべてのプロダクトに定義されているすべてのスコープを「認識」します。
アプリでアクセストークンをリクエストすると、適用するスコープを指定できます。（a）リクエストされたスコープと（b）デベロッパーアプリで認識されたスコープに基づいて、アクセストークンに実際に割り当てるスコープを決定するのは Apigee（認可サーバー）です。
Apigee がスコープを確認する構成になっていない場合（<Scope> 要素が VerifyAccessToken ポリシーに含まれていない場合、または空の場合）、アクセストークンに埋め込まれたスコープが登録されたデベロッパーアプリで認識されるスコープ（アプリのスコープ「マスター」リストにあるいずれかのスコープ）と一致すれば API 呼び出しは成功します。
アクセストークンにスコープが 1 つも関連付けられていない場合、API 呼び出しが成功するのは Apigee がスコープを考慮しない場合（VerifyAccessToken ポリシーに <Scope> 要素がないか、値が空の場合）だけです。