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

トークン メタデータについて

Apigee Edge は OAuth アクセス トークン、リフレッシュ トークン、認可コードを生成して、認証されたアプリに分配します。生成時に、Edge がこれらのトークンとコードを保管します。以降、Edge はこれらのトークンやコードを含んだ受信 API リクエストを受け取ると、保管された情報を使用してリクエストを認可します。

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

Edge アクセス トークンの 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 Edge では、こういったのデータは「カスタム属性」と呼ばれます。次に、トークンが 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 Edge はトークンストアでトークンを検索することにより、トークンを検証します。Apigee Edge がその後、トークンに関する情報を含んだコンテキスト変数のセットを入力します。たとえば、次のようなものです。

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

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

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

カスタム属性をランタイム時に設定して更新する

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

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

Edge API を使用して、トークンに添付されたカスタム属性を更新することもできます。API ドキュメントで OAuth 2.0 アクセス トークンの更新メソッドについてご覧ください。