「JWT ベースのアクセストークン」の利用
概要
Authlete には JWT 形式のアクセストークンを発行する機能があります。本記事では、この機能を有効化する方法と、アクセストークンに追加のクレームを指定する方法について説明します。
機能の有効化
登録後、「トークン」タブに移動し、適切な「アクセストークン署名アルゴリズム」を選択します。たとえば ES256 の署名鍵を登録した場合(上記の記事の例)には、「ES256」を選択します。
設定後、Authlete の発行するアクセストークンは JWT 形式となります。
追加のプロパティをアクセストークンに埋め込む
任意の Key/Value の組をアクセストークンに埋め込むには 2 つの方法があります。
- Extra Properties 機能を利用して文字列の値を追加する
- 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 へのリクエスト時に利用可能です。
- /auth/authorization/issue
- /auth/token/issue
- /auth/token/create
- /backchannel/authentication/complete
- /device/complete
jwtAtClaims に指定する値の形式は JSON オブジェクトです。jwtAtClaims に指定された JSON オブジェクト内のプロパティ群が、JWT アクセストークンのペイロード部に追加されます。
動作例
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?