トークンに任意のプロパティをひもづける方法

概要


Authlete では、アクセストークンまたは認可コードに任意のプロパティ群 (properties) をひもづける機能を持っています。この機能により、認可サーバーはリソースサーバーに対し、API リクエストの可否判定やリクエストの処理内容に必要な情報を提供しやすくなります。

たとえば送金機能をもつ銀行 API において「ABC商店へ5,000円を送金する」といった機能を実現するとしましょう。これを「ABC商店へ5,000円を送金する」というスコープを作って実現しようとすると、送金先および送金額を組み合わせた数のスコープが必要になってしまいます。これは現実的ではありません。

Authlete のプロパティを用いると、認可サーバーがクライアントに対して発行するアクセストークンに、上記の情報をプロパティーとして直接埋め込む、ないしは、上記情報を管理する DB のレコードにひもづけておくことができます。クライアントからアクセストークンを受け取った銀行 API は、そのトークンにひもづいているプロパティから上記の情報を取得し、送金可否の判断が可能となります。

あるいはリソースサーバーが、クライアントから提示されたアクセストークンから、そのトークンにひもづくユーザーの識別子だけではなく、ユーザーの属するグループやロールを知りたいとしましょう。単純な実現方法としては、リソースサーバーは受け取ったアクセストークンのイントロスペクションを行ってユーザー識別子を取得した上で、そのユーザーのグループやロールを得るために、別のデータベースに問い合わせを行うことになります。

これもまた、Authlete のプロパティを用いると、認可サーバーがユーザーのグループやロールをトークンにひもづけ、その値をリソースサーバーが Authlete から取得する、という連携が可能となり、前述したような、リソースサーバーからデータベースへの問い合わせが不要となります。


設定方法


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

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

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

このプロパティをアクセストークンにひもづけた場合、認可サーバーからクライアントへのトークンレスポンスは次のようになります。


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

また、リソースサーバーが Authlete の /auth/introspection API を呼び出すと、そのレスポンスには以下のようにプロパティが含まれます。

{
  "clientId" : <Client ID>,
  "properties" : [
    {
      "key":"example_parameter",
      "value":"example_value",
      "hidden" : true
   }
  ],
"sufficient" : true, "action" : "OK", "clientIdAliasUsed" : false, "resultCode" : "A056001", "expiresAt" : 1565847795000, "subject" : "<Subject>", "type" : "introspectionResponse", "refreshable" : true, "usable" : true, "existent" : true, "resultMessage" : "[A056001] The access token is valid.", "responseContent" : "Bearer error=\"invalid_request\"" }


実装方法


アクセストークンへのプロパティのひもづけは、下記のタイミングで行います。

  1. 認可サーバーが「認可エンドポイント」から認可コードもしくはアクセストークンを返却する直前
  2. 認可サーバーが「トークンエンドポイント」からアクセストークンを返却する直前

例えば上記 1 の場合、/auth/authorization/issue API を呼び出す際に、以下のようにプロパティをセットします。

{ "ticket": "<ticket>", "subject": "<subject>", "properties":[{"key":" example_parameter","value":"example_value","hidden":true}] }


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

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


制限事項

  1. プロパティのキーに次のものを使うことはできません。指定された場合には Authlete サーバーが破棄します。 理由は、これらが認可サーバーから返される応答に含まれるパラメーター群として、 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?