Table of Contents

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

概要

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

本機能は Authlete 2.1 以降で利用可能です。

機能の有効化

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

Authlete サービスの JWK セット設定

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

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

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

任意の Key/Value の組をアクセストークンに埋め込むには 2 つの方法があります。

Extra Properties 機能を利用して文字列の値を追加する
jwtAtClaims パラメーターを利用して任意のクレームを追加する

それぞれの方法について、概要を以下に示します。

jwtAtClaims パラメーターは Authlete 2.3 以降で利用可能です。

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"
        ]
    },
    ...
}