Using JWT-based access tokens

Preface


Authlete has a feature that can issue JWT-formatted access tokens. This article describes how to enable the feature, and how to specify additional claims to an access token.




Enabling the feature


Register a JWK set document to "JWK Set Content" section in Service Settings. See the following article for instructions. 


After the registration, choose an appropriate "Access Token Signature Algorithm" in the same "Token" tab. For example, you would choose "ES256" if you have registered an ES256 signing key (shown in the article above).

Access Token Signature Algorithm


After the change, access tokens to be issued by Authlete are JWT-formatted. 

Embedding additional properties into access tokens


You can embed arbitrary key-value pairs into access tokens in either of the following ways:
  1. Adding string values using “Extra Properties”
  2. Adding arbitrary claims using jwtAtClaims parameter
The following sections describe the overview.


1. Adding string values using “Extra Properties”


The “Extra Properties” feature allows an authorization server to associate arbitrary properties with either an access token or an authorization code. By using this feature for the JWT-formatted access tokens, visible (= not-hidden) extra properties are included in the access tokens as custom claims so that resource servers can extract them.

Example


The following is an execution example of /auth/token API of the Authlete service configured to issue JWT-formatted access tokens. This example also shows output when using extra properties.

You will see a JWS signed JWT as a value of "access_token" in "responseContent" (content of token response). The same value is also provided as "jwtAccessToken". (folded for readability)

  • Request
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=..."
}

  • Response
{
  "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"
}

Header and payload of the JWT access token are as follows.  The latter includes the extra properties ("example_parameter":"example_value"). 

  • Header
{
  "kid": "1",
  "alg": "ES256"
}

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

2. Adding arbitrary claims using jwtAtClaims parameter


The jwtAtClaims request parameter allows you to add JSON objects as claims to a JWT access token. This parameter is available when making a request to the following Authlete APIs.
The format of the value specified for jwtAtClaims is a JSON object. The properties in the JSON object specified in jwtAtClaims will be added to the JWT access token payload.

Example


Below is an example using jwtAtClaims as one of the parameters of the request to the /auth/authorization/issue API.

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

The resulting JWT access token looks like this:

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

See also


How did we do with this article?