「JWT ベースのアクセストークン」の利用

概要


Authlete には JWT 形式のアクセストークンを発行する機能があります。本記事では、この機能を有効化する方法と、アクセストークンに追加のクレームを指定する方法について説明します。


機能の有効化


サービス設定の「JWK セットの内容」に JWK セットドキュメントを登録します。手順については以下の記事をご参照ください。


登録後、「トークン」タブに移動し、適切な「アクセストークン署名アルゴリズム」を選択します。たとえば ES256 の署名鍵を登録した場合（上記の記事の例）には、「ES256」を選択します。

設定後、Authlete の発行するアクセストークンは JWT 形式となります。

追加のプロパティをアクセストークンに埋め込む


任意の Key/Value の組をアクセストークンに埋め込むには 2 つの方法があります。
  1. Extra Properties 機能を利用して文字列の値を追加する
  2. jwtAtClaims パラメーターを利用して任意のクレームを追加する
それぞれの方法について、概要を以下に示します。


1. Extra Properties 機能を利用して文字列の値を追加する


Extra Properties を用いると、認可サーバーは任意のプロパティをアクセストークンや認可コードに関連づけることができます。この機能を JWT 形式のアクセストークンに用いると、関連付けたプロパティのうち、クライアントに開示されるよう指定した（"hidden":false の）ものが、カスタムクレームとしてアクセストークンに含まれます。リソースサーバーはこれらのクレームを抽出して利用できるようになります。

動作例


以下は、JWT 形式のアクセストークンを発行するよう Authlete サービスを設定した場合の /auth/token API の動作例です。またこの例では Extra Properties を用いた場合の出力を示しています（一部折り返しています）。

"jwtAccessToken" の値、ならびに "responseContent" （トークンレスポンスの内容）の値に含まれる "access_token" の値が JWS signed JWT になっています。

  • リクエスト
POST https://eaxample.authlete.com/api/auth/token
Authorization: {{API_Key/API_SECRET}}
Content-Type: application/json

{
  "clientId":"...",
  "clientSecret":"...",
  "parameters":
    "grant_type=authorization_code&
     redirect_uri=https://client.example.org/cb/example.com&
     code=..."
}

  • レスポンス
{
  "type": "tokenResponse",
  "resultCode": "A050001",
  "resultMessage": "[A050001] The token request 
    (grant_type=authorization_code) was processed successfully.",
  "accessToken": "xx2...AFQ",
  "accessTokenDuration": 86400,
  "accessTokenExpiresAt": 1591690046802,
  "action": "OK",
  "clientId": 17201083166161,
  "clientIdAliasUsed": false,
  "grantType": "AUTHORIZATION_CODE",
  "jwtAccessToken": "eyJraWQiOiIxIiwiYWxnIjoiRVMyNTYifQ.
    eyJleGFtcGxlX3BhcmFtZXRlciI6ImV4YW1wbGVfdmFsdWUiLCJz
    dWIiOiJ0ZXN0dXNlcjAxIiwic2NvcGUiOm51bGwsImlzcyI6Imh0
    dHBzOi8vYXV0aGxldGUuY29tIiwiZXhwIjoxNTkxNjkwMDQ2LCJp
    YXQiOjE1OTE2MDM2NDYsImNsaWVudF9pZCI6IjE3MjAxMDgzMTY2
    MTYxIiwianRpIjoieHgycnNJODBER1Z4bHFLdTFQV2R4eWJSLTdB
    eTZWamJNcTAxY3dNYkFGUSJ9.
    -9RsKUSnJHmdqNtNpWbbbTah1YxTkicsabIgxrLWHtGiLsTIaEj_
    q39AvKYWrmfnw5y0dfaD3qtTScxI94OSIg",
  "properties": [
    {
      "hidden": false,
      "key": "example_parameter",
      "value": "example_value"
    }
  ],
  "refreshToken": "4rA7H1uRZkCQ7Yd0PN98h7IUqW7zT8p1a_BAg0jEyow",
  "refreshTokenDuration": 864000,
  "refreshTokenExpiresAt": 1592467646802,
  "responseContent": "{\"access_token\":
    \"eyJraWQiOiIxIiwiYWxnIjoiRVMyNTYifQ.
      eyJleGFtcGxlX3BhcmFtZXRlciI6ImV4YW1wbGVfdmFsdWUiLCJz
      dWIiOiJ0ZXN0dXNlcjAxIiwic2NvcGUiOm51bGwsImlzcyI6Imh0
      dHBzOi8vYXV0aGxldGUuY29tIiwiZXhwIjoxNTkxNjkwMDQ2LCJp
      YXQiOjE1OTE2MDM2NDYsImNsaWVudF9pZCI6IjE3MjAxMDgzMTY2
      MTYxIiwianRpIjoieHgycnNJODBER1Z4bHFLdTFQV2R4eWJSLTdB
      eTZWamJNcTAxY3dNYkFGUSJ9.
      -9RsKUSnJHmdqNtNpWbbbTah1YxTkicsabIgxrLWHtGiLsTIaEj_
      q39AvKYWrmfnw5y0dfaD3qtTScxI94OSIg\",
    \"refresh_token\":\"4rA7H1uRZkCQ7Yd0PN98h7IUqW7zT8p1a_BAg0jEyow\",
    \"example_parameter\":\"example_value\",
    \"scope\":null,
    \"token_type\":\"Bearer\",
    \"expires_in\":86400}",
  "subject": "testuser01"
}

上記の JWT アクセストークンの、ヘッダーとペイロードは以下の通りです。ペイロードには Extra Properties ("example_parameter":"example_value") が含まれています。

  • ヘッダー
{
  "kid": "1",
  "alg": "ES256"
}

  • ペイロード
{
  "example_parameter": "example_value",
  "sub": "testuser01",
  "scope": null,
  "iss": "https://authlete.com",
  "exp": 1591690046,
  "iat": 1591603646,
  "client_id": "17201083166161",
  "jti": "xx2rsI80DGVxlqKu1PWdxybR-7Ay6VjbMq01cwMbAFQ"
}


2. jwtAtClaims パラメーターを利用して任意のクレームを追加する


 jwtAtClaims リクエストパラメーターを用いると、JSON オブジェクトを JWT アクセストークンのクレームとして追加できます。このパラメーターは下記の Authlete API へのリクエスト時に利用可能です。
jwtAtClaims に指定する値の形式は JSON オブジェクトです。jwtAtClaims に指定された JSON オブジェクト内のプロパティ群が、JWT アクセストークンのペイロード部に追加されます。

動作例


以下は、/auth/authorization/issue API へのリクエストのパラメーターのひとつに jwtAtClaims を用いる例です。

POST https://eaxample.authlete.com/api/auth/authorization/issue
Authorization: {{API_Key/API_SECRET}}
Content-Type: application/json

{ 
    "ticket": "{{ticket}}",
    "subject": "abc",
    "jwtAtClaims": "{\"realm_access\": {\"roles\":[\"A\", \"B\"]}}" 
   ...
}

この結果、生成される JWT アクセストークンは、以下のようになります。

{
  "sub": "abc",
  "iss": "https://example.authlete.com",
  "realm_access": {
    "roles": [
      "A",
      "B" 
    ]
  },
  ...
}




参考情報


How did we do with this article?