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.

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)


  • 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



How did we do with this article?