トークンに任意のパラメーターを紐づける

概要

Authlete では、アクセストークンまたは認可コードに任意のプロパティー群(properties)を紐づける機能を持っています。

例えば、送金機能をもつ銀行 API において「ABC商店へ5,000円を送金する」といった機能を実現したい!、という状況を想定します。その際アクセストークンに、上記の情報をプロパティーとして直接埋め込む、ないしは、上記情報を管理する DB のレコードに紐づけることで比較的容易に上記の機能を実現させることができます。

なお、上記機能は、「ABC商店へ5000円を送金する」というスコープを作る事でも実現しえますが、その場合、送金先および送金額の組み合わせの数だけスコープを準備することになるため、柔軟性を欠きます。

 詳細


Authlete では、アクセストークンないしは認可コードに任意のパラメーターを紐づけする際、プロパティー(プロパティー)というクラスを利用します。ここでプロパティーとは、key と value というエントリーを持つ JSON オブジェクトで、それぞれの値は文字列となります。文字通り、key は プロパティーのキーを、value はプロパティーの値を表します。

次の JSON は、キーと値がそれぞれ example_parameter、example_value であるプロパティーの例です。

{
                              "key":"example_parameter",
                              "value":"example_value"
                          }

例えば上記のようなプロパティーをアクセストークンに紐づけた場合、認可サーバーからのアクセストークンの応答は次のようになります。

{
                              "access_token":"pNj1h24a4geA_YHilxrshkRkxJDsyXBZWKp3hZ5ND7A",
                              "token_type":"Bearer",
                              "expires_in":86400,
                              "scope":null,
                              "example_parameter":"example_value"
                          }

実装方法


上記のプロパティーの紐づけは、下記のタイミングで行います。

  1. 認可サーバー側の「認可エンドポイント」でクライアントからのリクエストを受け取った後、Authlete の「認可エンドポイント」を呼ぶまでの間
  2. 認可サーバー側の「トークンエンドポイント」でリクエストを受取った後、Authlete の「トークンエンドポイント」または「トークンイシューエンドポイント」を呼ぶまでの間

例えば上記1の場合、authlete-java-jaxrs ライブラリの AuthorizationDecisionHandlerSpiAdapter クラス にある getProperties メソッドを変更することで、任意のプロパティーを紐づけすることができます(デフォルトでは、 null が返されます)。

詳細は、公式ドキュメントAPI ドキュメント 、Github 上の各種実装例をご参考ください。

制限事項

  1. プロパティーのキーに次のものを使うことはできません。指定しても、サーバー側で破棄します。 理由は、認可サーバーから返される応答に含まれるパラメーター群として、 RFC 6749OpenID Connect Core 1.0 で予約されているためです。
    • access_token
    • token_type
    • expires_in
    • refresh_token
    • scope
    • error
    • error_description
    • error_uri
    • id_token
  2. プロパティーの値には文字列しか指定できません。真偽値や配列等は指定できません。
  3. 長さ制限があります。指定されたプロパティー群は、次のような処理を経てサーバー側のデータベース内に保存されます。下記手順で生成された base64url 文字列の長さが 65,535 を超える場合、エラーとなります。
    1. 三次元の文字列に変換する (例:[["example_parameter","example_value",null]])
      (hidden の値は null か空文字列に変換されます。それぞれ、false と true を表します。)
    2. JSON 文字列に変換する (例: "[[\"example_parameter\":\"example_value\",null]]")
    3. AES/CBC/PKCS5Padding で暗号化する
    4. base64url でエンコードする





How did we do with this article?