トークンと認証コードのカスタマイズ

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

Apigee Edge のドキュメントはこちらをご覧ください。

トークンと認証コードのメタデータについて

Apigee は OAuth アクセス トークン、更新トークンと認証コードを生成し、認証されたアプリに渡します。生成時に、Apigee はこれらのトークンとコードを保存します。その後、Apigee がこれらのトークンまたはコードが含まれている受信 API リクエストを受信すると、Apigee は保存されている情報を使用してリクエストを承認します。

Apigee がこれらの OAuth アーティファクトを生成する際は、トークンまたはコードにメタデータも添付されます。たとえば、アクセス トークンは、有効期限、関連するアプリとデベロッパー、その他の情報を定義する名前と値のペアに関連付けられます。

Apigee アクセス トークンの JSON 表現は、以下のようになります。

{
  "issued_at" : "1372170159093",
  "application_name" : "ccd1803b-b557-4520-bd62-ddd3abf8e501",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[Product1,Product2]",
  "api_product_list_json" : ["Product1", "Product2"],
  "expires_in" : "3599", //--in seconds
  "developer.email" : "joe@weathersample.com",
  "organization_id" : "0",
  "refresh_token" : "82XMXgDyHTpFyXOaApj8C2AGIPnN2IZe",
  "client_id" : "deAVedE0W9Z9U35PAMaAJYphBJCGdrND",
  "access_token" : "shTUmeI1geSKin0TODcGLXBNe9vp",
  "organization_name" : "apifactory",
  "refresh_count" : "0"
}

OAuth トークンと認証コードへのカスタム属性の追加

場合によっては、アクセス トークンにカスタム属性を追加すると便利です。たとえば、ユーザー名、ユーザーのグループ メンバーシップまたはロール、お客様 ID、セッション識別子、または他の任意情報をトークンに追加するとよいでしょう。Apigee では、こういったデータは「カスタム属性」と呼ばれます。その後でトークンが API リクエストのスコープ内で検証されると、このデータはコンテキスト変数を介して API プロキシで使用可能になります。API プロキシは、トークンに添付されたカスタムデータに基づいて、きめ細かな認可またはルーティング決定を行うことができます。

トークンに任意のデータを添付するには、OAuthV2 ポリシーで <Attributes> 要素を使用します。カスタム属性の名前と値は指定できます。たとえば、以下に示すのは、トークンを生成してカスタム属性の「tenant_list」を添付するポリシー構成です。

<OAuthV2 name="GenerateAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>600000</ExpiresIn>
  <GenerateResponse />
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <Attributes> 
    <Attribute name="tenant_list" ref="tenant_list_retrieved_from_external_service" display="false"/>
  </Attributes>
</OAuthV2>

複数のカスタム属性を指定し、認証コード（<Operation>GenerateAuthorizationCode</Operation>）またはトークン（<Operation>GenerateAccessToken</Operation>）の生成時に暗黙的に関連付けることができます。

display が true（デフォルト）に設定されている場合、カスタム属性はレスポンスで返され、アプリで表示するか、エンドユーザーに渡すことができます。display が false に設定されている場合、カスタム属性はデータストアに格納されますが、レスポンス メッセージでは返されません。どちらの場合も、カスタムデータを API プロキシ内のポリシーが使用可能になるのは、トークンが検証された後です。

display オプションに関する詳細は、レスポンスでカスタム属性を表示または非表示にするをご覧ください。

アクセス トークンのカスタム属性を実行時に取得する

OAuthV2/VerifyAccessToken に対する呼び出しがあると、Apigee はトークンストアでトークンを検索して検証します。Apigee は次に、トークンに関する情報を含むコンテキスト変数のセットを入力します。たとえば、次のようなものが挙げられます。

  • organization_name
  • developer.id
  • developer.app.name
  • client_id
  • grant_type
  • token_type
  • access_token
  • issued_at
  • expires_in //--in seconds
  • status
  • scope
  • apiproduct.name*

トークンにカスタム属性がある場合、それらのカスタム属性は accesstoken.{custom_attribute} という名前のコンテキスト変数で使用可能になります。たとえば、上記のポリシーからトークンが発行されたとします。このトークンを検証すると、トークンの生成時に格納された値を含む accesstoken.tenant_list という名前のコンテキスト変数が追加されます。

ポリシーまたは条件がこれらの値を参照でき、中に保管された値に基づいて動作を変更できます。

カスタム属性を実行時に設定して更新する

場合によっては、実行時に Apigee で API 呼び出しを処理している間に、アクセス トークンに関連付けられたメタデータを API プロキシで更新したいことがあります。これを可能にするために、Apigee はトークン属性を取得および設定するためのポリシーを提供しています。詳細については、Get OAuth V2 Info ポリシーと Set OAuth V2 Info ポリシーをご覧ください。

これらの各ポリシーで、アクセス トークンが含まれる変数を AccessToken 要素が参照する必要があります。