Migrating access tokens issued by other system to Authlete

Preface

On replacing existing authorization server system (old system) to Authlete, you might have to consider how to manage access tokens which are issued by the old system.
If you want Authlete to verify both old and new access tokens coming from resource servers (i.e. resource servers don’t distinguish between old and new ones), both kinds of tokens must be managed by Authlete.

This article explains practice to migrate the access tokens issued by other system to Authlete.

How to migrate

Authlete provides /auth/token/create , one of token management APIs. It enables authorization server to have Authlete to create arbitrary tokens without any authorization request as well as token request. The following section in API reference explains parameters for the API.

• /auth/token/create API

The accessToken parameter is optional but important one. If some value are specified to the parameter, Authlete takes it as a value of access token which is newly minted. By the way, Authlete hashes the value and stores it into token database.

Thus you can achieve token migration using this API to create a token, with the accessToken parameter specified a value of an existing token issued by the old system.

Example

Creating tokens

An administrator, who has information of previously issued tokens, makes a request to /auth/token/create API to create new tokens with the old values. (folded for readability)

• Request

curl -s -X POST .../auth/token/create  \
  -u ...:... \
  -H 'Content-type: application/json' \
  -d '{"grantType":"AUTHORIZATION_CODE", \
       "clientId":"...", \
       "subject":"john", \
       "accessToken":"existingAccessTokenValue
", \
       "accessTokenDuration":3600, \
       "refreshToken":"existingRefreshTokenValue
", \
       "refreshTokenDuration":86400, \
       "properties":[ \
          { \
            "hidden":true, \
            "key":"amount", \
            "value":"100" \
          } \
        ], \
       "scopes":["openid","payment"]}'

• Response

{
   "type": "tokenCreateResponse",
   "resultCode": "A109001",
   "resultMessage": "[A109001] An access token was created successfully: authorization_code, client = 17201083166161",
   "accessToken": "existingAccessTokenValue
",
   "action": "OK",
   "clientId": 17201083166161,
   "expiresAt": 1594020768318,
   "expiresIn": 3600,
   "grantType": "AUTHORIZATION_CODE",
   "properties": [
      {
         "hidden": true,
         "key": "amount",
         "value": "100"
      }
   ],
   "refreshToken": "existingRefreshTokenValue
",
   "scopes": [
      "openid",
      "payment"
   ],
   "subject": "john",
   "tokenType": "Bearer"
}

Introspection

On receiving an API request with “the previously issued access token,” a resource server attempts to verify the token and obtain its related information. The following example shows these operations using Authlete’s /auth/introspection API . (folded for readability)

If you are using JWT-formatted access tokens , resource servers are responsible to verify the tokens and extract the related information.

• Request

curl -s -X POST \
.../auth/introspection \
-u ...:... \
-H 'Content-type: application/json' \
-d '{"token":"existingAccessTokenValue
"}'

• Response

{
    "type": "introspectionResponse",
    "resultCode": "A056001",
    "resultMessage": "[A056001] The access token is valid.",
    "action": "OK",
    "clientId": 17201083166161,
    "clientIdAliasUsed": false,
    "existent": true,
    "expiresAt": 1594020768000,
    "properties": [
        {
            "hidden": true,
            "key": "amount",
            "value": "100"
        }
    ],
    "refreshable": true,
    "responseContent": "Bearer error=\"invalid_request\"",
    "scopes": [
        "openid",
        "payment"
    ],
    "subject": "john",
    "sufficient": true,
    "usable": true
}

Refreshing tokens

On receiving a refresh token request with “the previously issued refresh token,” an authorization server attempts to process the token request by calling Authlete’s  /auth/introspection API . (folded for readability)

• Request

curl -s -X POST $AL_API/auth/token \
-u $AL_SVC \
-H 'Content-type: application/json' \
-d '{
  "clientId": "...",
  "clientSecret": "...",
  "parameters": "grant_type=refresh_token
  &refresh_token=existingRefreshTokenValue
"
}'

• Response

{
    "type": "tokenResponse",
    "resultCode": "A053001",
    "resultMessage": "[A053001] The token request (grant_type=refresh_token) was processed successfully.",
    "accessToken": "a4utoeZ-R3WwpbD2q-HbNBlEkie2GZZyrdAmmoeuKd0",
    "accessTokenDuration": 300,
    "accessTokenExpiresAt": 1594018713161,
    "action": "OK",
    "clientId": 17201083166161,
    "clientIdAliasUsed": false,
    "grantType": "REFRESH_TOKEN",
    "properties": [
        {
            "hidden": true,
            "key": "amount",
            "value": "100"
        }
    ],
    "refreshToken": "9JhH1r5-Q54-XApNhGmSS_dxwwUp_SjjoaX81gev_po",
    "refreshTokenDuration": 900,
    "refreshTokenExpiresAt": 1594019313161,
    "responseContent": "{\"access_token\":\"a4utoeZ-R3WwpbD2q-HbNBlEkie2GZZyrdAmmoeuKd0\", \"refresh_token\":\"9JhH1r5-Q54-XApNhGmSS_dxwwUp_SjjoaX81gev_po\", \"scope\":\"openid payment\", \"token_type\":\"Bearer\", \"expires_in\":300}",
    "scopes": [
        "openid",
        "payment"
    ],
    "subject": "john"
}

For migrating enormous tokens

If you are going to migrate tokens enormously, it might by appropriate to take another method; dump token information from the old system, and then transform and import them to Authlete. Please ask Authlete support representative for details.

Supplemental information

• New Architecture of OAuth 2.0 and OpenID Connect Implementation

  • 6.1. Access Token Creation

Authlete’s /api/auth/token/create API is an example. By using the API, developers can create access tokens without user interaction.