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

はじめに

アクセストークンを含む API リクエストを受け取ったリソースサーバーは、そのトークンに付随する情報をもとに、API アクセスの可否や、レスポンスの内容を決定します。基本的な付随情報としてはたとえば、トークンの状態（有効・無効）や、誰（リソースオーナー）が何（クライアント）にどのようなアクセス権（スコープ）を移譲したかなどですが、場合によっては、認可サーバーからさらに他の関連情報を得る必要があります。 Authlete では、アクセストークンまたは認可コードに任意のプロパティ群 (properties) をひもづける機能を持っています。この機能により、認可サーバーはリソースサーバーに対し、API リクエストの可否判定やリクエストの処理内容に必要な情報を提供しやすくなります。また、プロパティの受け渡しはクライアントを介さずに行うことが可能であり、不必要な情報露見を防止できます。

ユースケース

例 1: 送金 API の制御

送金機能をもつ銀行 API において「ABC商店へ5,000円を送金する」といった機能を実現するとします。これを「ABC商店へ5,000円を送金する」というスコープを作って実現しようとすると、送金先および送金額を組み合わせた数のスコープが必要になってしまいます。これは現実的ではありません。 Authlete のプロパティを用いると、認可サーバーがクライアントに対して発行するアクセストークンに、上記の情報をプロパティとして直接埋め込む、ないしは、上記情報を管理する DB のレコードにひもづけておくことができます。クライアントからアクセストークンを受け取った銀行 API は、そのトークンにひもづいているプロパティから上記の情報を取得し、送金可否の判断が可能となります。

例 2: ロールベースのアクセス管理

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

利用方法

本セクションではプロパティの設定・取得の利用方法を紹介します。

Extra properties

Property データタイプ

Authlete では、アクセストークンないしは認可コードにひもづけるプロパティ（任意のパラメーター群）を、Property データタイプとして定義しています。Property データタイプは次のようなエントリーを持つ JSON オブジェクトです。

名前	型	説明
key	文字列	プロパティのキー
value	文字列	プロパティの値
hidden	真偽値	プロパティをクライアントから秘匿するか否かを示すフラグ。true の場合には秘匿する。false の場合には秘匿しない（クライアントに露見する）。

たとえば、キーが example_key、値が example_value であり、クライアントから秘匿しない（クライアントへの露見を許容する）プロパティは、以下のような JSON オブジェクトになります。

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

プロパティのひもづけ

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

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

認可サーバーが /auth/authorization/issue API を呼び出す際にプロパティをセットします。以下は curl コマンドによる実行例です。（見やすさのため折り返しています）

リクエスト

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization/issue \
     -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
     -H 'Content-Type: application/json' \
     -d '{"subject":"<subject>",
          "ticket":"<ticket>",
          "properties":[
              {"key":"example_key", "value":"example_value", "hidden":true}
          ]
     }'

レスポンス

{
    "resultCode": "A040001",
    "resultMessage": "[A040001] The authorization request was processed successfully.",
    "accessTokenDuration": 0,
    "accessTokenExpiresAt": 0,
    "action": "LOCATION",
    "authorizationCode": "...",
    "responseContent": "https://client.example.org/cb/example.com?code=...&iss=https%3A%2F%2Fauthlete.com"
}

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

認可サーバーが「トークンエンドポイント」からアクセストークンを返却する直前

認可サーバーが /auth/token API を呼び出す際にプロパティをセットします。以下は curl コマンドによる実行例です。（見やすさのため折り返しています）

リクエスト

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
   -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
   -H 'Content-Type: application/json' \
   -d '{
        "clientId": "<clientId>",
        "clientSecret": "<clientSecret>",
        "parameters": "redirect_uri=https://client.example.org/cb/example.com&grant_type=authorization_code&code=...",
        "properties": [
            {"key": "example_key", "value": "example_value", "hidden": false}
        ]
    }'

レスポンス

{
  "resultCode": "A050001",
  "resultMessage":
    "[A050001] The token request (grant_type=authorization_code) was processed
     successfully.",
  "accessToken": "...",
  "action": "OK",
...
  "properties": [
    {
      "hidden": false,
      "key": "example_key",
      "value": "example_value"
    }
  ],
  "refreshToken": "...",
  "responseContent":
    "{\"access_token\":\"...\",
      \"refresh_token\":\"...\",
      \"scope\":\"payment\",
      \"token_type\":\"Bearer\",
      \"expires_in\":300,
      \"example_key\":\"example_value\"     }",
  "subject": "<subject>"
}

ここでは “hidden”:false としているため、トークンレスポンスの一部として、あるいは JWT 形式のアクセストークンを用いた場合にはそのペイロードとして、プロパティがクライアントに開示されます。プロパティをリソースサーバーだけに開示し、クライアントから秘匿する場合には、この値を false ではなく true とします。

プロパティの取得

リソースサーバーが /auth/introspection API を呼び出すと、そのレスポンスにプロパティが含まれます。以下は curl コマンドによる実行例です。（見やすさのため折り返しています）

リクエスト

curl -s -X POST \
https://us.authlete.com/api/${SERVICE_API_KEY}/auth/introspection \
-H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-d '{"token":"<accessToken>"}'

レスポンス

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

フローごとの例

プロパティを渡す API は、フローによって異なります。アクセストークンを発行する API がフローごとに違うためです。ここでは、フローごとに properties パラメーターを受け取る API 呼び出しと、その結果としてクライアントおよびリソースサーバーが受け取る内容を示します。以下の例では、プロパティとして example_parameter=example_value を使用します。${SERVICE_API_KEY} はサービス ID、Bearer トークンはサービスアクセストークンです。

認可コードフロー

クライアントからの認可リクエストを /auth/authorization API に渡します。レスポンスには action: INTERACTION と ticket が含まれ、ticket は次の呼び出しで使用します。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "client_id=1048476397&response_type=code&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&scope=timeline.read" }'

/auth/authorization/issue API で認可コードを発行します。ここで渡したプロパティは認可コードにひもづき、その認可コードと引き換えに発行されるアクセストークンへ引き継がれます。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization/issue \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "ticket": "XhPCGRCuKw4QYShCB59yQ-5jq258hZaZ-2QNhdmsUZg",
        "subject": "user123",
        "properties": [
            {"key": "example_parameter", "value": "example_value"}
        ]
      }'

{
  "resultCode": "A040001",
  "resultMessage": "[A040001] The authorization request was processed successfully.",
  "action": "LOCATION",
  "authorizationCode": "HSwoz1hLb-qaEo5oUFhGHZdpdTevHNIrhJotOpOg0_o",
  "responseContent": "https://client.example.org/cb?code=HSwoz1hLb-qaEo5oUFhGHZdpdTevHNIrhJotOpOg0_o&iss=https%3A%2F%2Fauthlete.com"
}

action: LOCATION は、認可サーバーがクライアントへ 302 Found を返し、responseContent の値を Location ヘッダーに使用することを表します。

認可コードを /auth/token API で交換します。この呼び出しでもプロパティを追加でき、手順 2 で渡したものとマージされます。同じキーが両方にある場合は、/auth/token に渡した値が優先されます。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "grant_type=authorization_code&code=HSwoz1hLb-qaEo5oUFhGHZdpdTevHNIrhJotOpOg0_o&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb",
        "clientId": "1048476397",
        "clientSecret": "${CLIENT_SECRET}",
        "properties": [
            {"key": "additional_parameter", "value": "additional_value"}
        ]
      }'

{
  "resultCode": "A050001",
  "resultMessage": "[A050001] The token request (grant_type=authorization_code) was processed successfully.",
  "action": "OK",
  "properties": [
    {
      "key": "additional_parameter",
      "value": "additional_value",
      "hidden": false
    },
    {
      "key": "example_parameter",
      "value": "example_value",
      "hidden": false
    }
  ],
  "accessToken": "LN-42WCA9hGmTbiKVfnyG8zFssh1S99YdLZ-uZ7Dg04",
  "refreshToken": "pbUei8l4-2cFL31zfBsaX9MO83SvNYmLfIJQxxYXAwU",
  "responseContent": "{\"access_token\":\"LN-42WCA9hGmTbiKVfnyG8zFssh1S99YdLZ-uZ7Dg04\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":\"timeline.read\",\"refresh_token\":\"pbUei8l4-2cFL31zfBsaX9MO83SvNYmLfIJQxxYXAwU\",\"additional_parameter\":\"additional_value\",\"example_parameter\":\"example_value\"}"
}

action: OK は、認可サーバーがクライアントへ 200 OK を返し、responseContent の値をレスポンスボディに使用することを表します。どちらのプロパティも hidden を指定していないため、クライアントに開示されます。

インプリシットフロー

アクセストークンは認可エンドポイントから発行されるため、プロパティを渡せるのは /auth/authorization/issue だけです。

response_type=token の認可リクエストを /auth/authorization API に渡し、レスポンスから ticket を取得します。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "client_id=1048476397&response_type=token&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb&scope=timeline.read" }'

/auth/authorization/issue API でアクセストークンを発行します。プロパティはここで渡します。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/authorization/issue \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "ticket": "j3OkWV4r8TEKeCTLPY8c_BfrYAbKYEy2FXZUaiYKAYU",
        "subject": "user123",
        "properties": [
            {"key": "example_parameter", "value": "example_value"}
        ]
      }'

{
  "resultCode": "A040001",
  "resultMessage": "[A040001] The authorization request was processed successfully.",
  "action": "LOCATION",
  "responseContent": "https://client.example.org/cb#access_token=VHnmJTwVdiS69oY_RLT9kYhdMUWqNdUEVHITdy_81ak&token_type=Bearer&expires_in=86400&scope=timeline.read&example_parameter=example_value&iss=https%3A%2F%2Fauthlete.com",
  "accessToken": "VHnmJTwVdiS69oY_RLT9kYhdMUWqNdUEVHITdy_81ak"
}

プロパティは、リダイレクト URI のフラグメントに access_token と並んで付加され、クライアントへ渡ります。

クライアントクレデンシャルズフロー

認可エンドポイントを経由しないため、プロパティはトークンリクエストとともに /auth/token へ渡します。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "grant_type=client_credentials&scope=timeline.read",
        "clientId": "1048476397",
        "clientSecret": "${CLIENT_SECRET}",
        "properties": [
            {"key": "example_parameter", "value": "example_value"}
        ]
      }'

{
  "resultCode": "A052001",
  "resultMessage": "[A052001] The token request (grant_type=client_credentials) was processed successfully.",
  "action": "OK",
  "properties": [
    {
      "key": "example_parameter",
      "value": "example_value",
      "hidden": false
    }
  ],
  "responseContent": "{\"access_token\":\"jC9TsQVcb0tE30pZ2jGu9S_fUB_r7AFACqcJOkl4HFA\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":\"timeline.read\",\"example_parameter\":\"example_value\"}"
}

このフローを使用するにはクライアントタイプがコンフィデンシャルである必要があり、リフレッシュトークンは発行されません（RFC 6749, 4.4.3）。

リソースオーナーパスワードクレデンシャルズフロー

トークンの発行が 2 段階に分かれており、プロパティを渡せるのは 2 番目の呼び出しだけです。

トークンリクエストを /auth/token API に渡します。レスポンスには action: PASSWORD と、クライアントが送信した username および password がそのまま含まれます。認可サーバーはこれらでユーザー認証を行います。

grant_type が password の場合、/auth/token に渡したプロパティは破棄されます。プロパティは /auth/token/issue に渡してください。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "grant_type=password&username=john&password=secret",
        "clientId": "1048476397",
        "clientSecret": "${CLIENT_SECRET}"
      }'

{
  "resultCode": "A051001",
  "resultMessage": "[A051001] Authlete has successfully issued a ticket to the service (API Key = 4239612149) for the token request from the client (ID = 1048476397). [grant_type=password]",
  "action": "PASSWORD",
  "username": "john",
  "password": "secret",
  "ticket": "gS1B19zO0c8DzN5jpac2PIWa9M1h2bFX9u6MzRi0X58"
}

ユーザー認証が完了したら、/auth/token/issue API でアクセストークンを発行します。認証されたユーザーを subject に、ひもづけるプロパティを properties に指定します。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token/issue \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "ticket": "gS1B19zO0c8DzN5jpac2PIWa9M1h2bFX9u6MzRi0X58",
        "subject": "user123",
        "properties": [
            {"key": "example_parameter", "value": "example_value"}
        ]
      }'

{
  "resultCode": "A054001",
  "resultMessage": "[A054001] The token request (grant_type=password) was processed successfully.",
  "action": "OK",
  "properties": [
    {
      "key": "example_parameter",
      "value": "example_value",
      "hidden": false
    }
  ],
  "responseContent": "{\"access_token\":\"jRdB_IwMkIyjvFkZTE5PBm1rbzz96x8Y0oF2MGagsVo\",\"token_type\":\"Bearer\",\"expires_in\":86400,\"scope\":null,\"refresh_token\":\"a3NqLMT87HKgLblRkg51ga-xCY3OI_voPvC5uzLxQDg\",\"example_parameter\":\"example_value\"}"
}

リフレッシュトークンフロー

grant_type=refresh_token で /auth/token に渡したプロパティは、そのリフレッシュトークンがひもづくアクセストークンが既に持つプロパティにマージされます。新しいキーは追加され、既にあるキーはここで渡した値で上書きされます。以下のリフレッシュトークンは認可コードフローで発行されたもので、そのアクセストークンは example_parameter と additional_parameter を持っています。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/token \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "parameters": "grant_type=refresh_token&refresh_token=pbUei8l4-2cFL31zfBsaX9MO83SvNYmLfIJQxxYXAwU",
        "clientId": "1048476397",
        "clientSecret": "${CLIENT_SECRET}",
        "properties": [
            {"key": "extra_parameter", "value": "extra_value"}
        ]
      }'

新しく発行されたアクセストークンは 3 つのプロパティを持ちます。リソースサーバーはこれをイントロスペクション API で取得します。

curl -s -X POST https://us.authlete.com/api/${SERVICE_API_KEY}/auth/introspection \
  -H 'Authorization: Bearer ${SERVICE_ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{ "token": "SJKrkYzT16OInwg0gKjC6bhPo9rUNRGRDMD1c8YUHNE" }'

{
  "resultCode": "A056001",
  "resultMessage": "[A056001] The access token is valid.",
  "action": "OK",
  "clientId": 1048476397,
  "subject": "user123",
  "properties": [
    {
      "key": "additional_parameter",
      "value": "additional_value",
      "hidden": false
    },
    {
      "key": "example_parameter",
      "value": "example_value",
      "hidden": false
    },
    {
      "key": "extra_parameter",
      "value": "extra_value",
      "hidden": false
    }
  ],
  "refreshable": true,
  "usable": true,
  "existent": true,
  "expiresAt": 1789564519772,
  "responseContent": "Bearer error=\"invalid_request\""
}

制限事項

キーの値

以下の値は認可サーバーから返される応答に含まれるパラメーター群として、 RFC 6749 と OpenID Connect Core 1.0 にて予約されているため、キーとして指定できません。指定された場合には Authlete サーバーが破棄します。

access_token
token_type
expires_in
refresh_token
scope
error
error_description
error_uri
id_token

プロパティの値

指定可能な値は文字列のみです。真偽値や配列等は指定できません。

サイズ

指定されたプロパティー群は、次のような処理を経て Authlete サーバー側のデータベース内に保存されます。最終的に生成された文字列の長さが 65,535 を超える場合にはエラーとなります。

三次元の文字列に変換する
- 例：[[“example_parameter”,“example_value”,null]] (hidden の値は null か空文字列に変換されます。それぞれ、false と true を表します。)
JSON 文字列に変換する
- 例: ”[[“example_parameter”:“example_value”,null]]”
AES/CBC/PKCS5Padding で暗号化する
base64url でエンコードする

エンドポイント

トークン & クレーム

鍵管理

メタデータ

エラー処理とデバッグ

セキュリティ

クライアント管理

サービス設定

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

はじめに

ユースケース

例 1: 送金 API の制御

例 2: ロールベースのアクセス管理

利用方法

Property データタイプ

プロパティのひもづけ

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

認可サーバーが「トークンエンドポイント」からアクセストークンを返却する直前

プロパティの取得

フローごとの例

認可コードフロー

インプリシットフロー

クライアントクレデンシャルズフロー

リソースオーナーパスワードクレデンシャルズフロー

リフレッシュトークンフロー

制限事項

キーの値

プロパティの値

サイズ

​はじめに

​ユースケース

​例 1: 送金 API の制御

​例 2: ロールベースのアクセス管理

​利用方法

​Property データタイプ

​プロパティのひもづけ

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

​認可サーバーが「トークンエンドポイント」からアクセストークンを返却する直前

​プロパティの取得

​フローごとの例

​認可コードフロー

​インプリシットフロー

​クライアントクレデンシャルズフロー

​リソースオーナーパスワードクレデンシャルズフロー

​リフレッシュトークンフロー

​制限事項

​キーの値

​プロパティの値

​サイズ

はじめに

ユースケース

例 1: 送金 API の制御

例 2: ロールベースのアクセス管理

利用方法

Property データタイプ

プロパティのひもづけ

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

認可サーバーが「トークンエンドポイント」からアクセストークンを返却する直前

プロパティの取得

フローごとの例

認可コードフロー

インプリシットフロー

クライアントクレデンシャルズフロー

リソースオーナーパスワードクレデンシャルズフロー

リフレッシュトークンフロー

制限事項

キーの値

プロパティの値

サイズ