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

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

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 プロキシがきめ細かな認可またはルーティング決定を、トークンに添付されたカスタムデータに基づいて行うことができます。

任意のデータをトークンに添付するには、<Attributes> 要素を OAuthV2 ポリシーで使用します。カスタム属性の名前と、使用される値を指定できます。たとえば以下のように、トークンを生成し、"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>)のどちらかに明示的に追加できます。

displaytrue (デフォルト)に設定されていると、レスポンスでカスタム属性が返されます。このときカスタム属性はアプリにより表示可能となるか、あるいはエンドユーザーに渡されます。displayfalse に設定されていると、カスタム属性はデータストア内に保管されますが、レスポンス メッセージで返されることはありません。どちらの場合も、カスタムデータを 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 アクセス トークンの更新メソッドについてご覧ください。