Refresh tokens after being used

Overview


“Refresh token grant” in OAuth 2.0
defines a mechanism for a client to request an authorization server to issue an access token (AT) by sending a previously issued refresh token (RT). The authorization server checks if the RT is valid, and then issues the new AT and sends it back to the client.

There are three choices for handling the used RT:
  • Keeping the RT valid for the next token refresh, 
  • Making the RT invalid and creating a new RT with a predefined duration, or
  • Making the RT invalid and creating a new RT with a remaining duration of the old RT. 
You can configure Authlete to support either one of choices. This article describes these characteristics for each one.





Keeping the used refresh token valid


An authorization server issues a new AT and sends it back to a client, while not invalidating the RT used for the token issuing process. The client is to use the RT in the next token refresh request.

Available duration for refreshing an AT is limited to the validity period of the RT.
refreshing-refresh-tokens-02.png 52.67 KB


Making the RT invalid and creating a new RT with a predefined duration


An authorization server issues a new RT along with a new AT and sends them back to a client. The RT used for the token issuing process is invalidated.

Available duration for refreshing an AT gets extended at every time RT are renewed.

Making the RT invalid and creating a new RT with a remaining duration of the old RT


An authorization server issues a new RT along with a new AT and sends them back to a client. The RT used for the token issuing process is invalidated.

The new RT's duration is set to the a remaining duration of the old RT. As a result, AT can be refreshed within a duration of the RT issued at the first token request.
refreshing-refresh-tokens-03.png 151.07 KB



Configuration


You can configure this setting through Service Owner Console. Choose “Kept” (i.e. keeping the used RT valid) or “Not kept” (i.e. invalidating the used RT) at “Refresh Token Continuous Use” section in “Token” tab.

When specifying “Not kept,” you can further choose “Enabled” or “Disabled” at  “Refresh Token Duration Takeover” section.

image.png 32.81 KB


Examples


The following examples are a sample request and responses when a client makes a token request using a RT (<refresh_token_1>).

  • Request
An authorization server makes a request to Authlete's /auth/token API to process the token request including the RT. Here is an example using curl. (folded for readability)

curl -s -X POST .../auth/token
 -u $apiKey:$apiSecret
 -H 'Content-type: application/json'
 -d '{"clientId":"...",
      "clientSecret":"...",
      "parameters":
        "grant_type=refresh_token
         &refresh_token=<refresh_token_1>"}'

  • Response if “Kept” (i.e. keeping the used RT valid)
Authlete sends back the same RT as being used (<refresh_token_1>) to the authorization server. Its duration is not initialized (in the example, 332 seconds left).

{
  "type": "tokenResponse",
  "resultCode": "A053001",
  "resultMessage": 
   "[A053001] The token request (grant_type=refresh_token)
      was processed successfully.",
  "accessToken": "...",
  "action": "OK",
  "grantType": "REFRESH_TOKEN",
  "refreshToken": "<refresh_token_1>",
  "refreshTokenDuration": 332,
  "refreshTokenExpiresAt": ...,
  "responseContent": 
    "{\"access_token\":\"...\",
      \"refresh_token\":\"<refresh_token_1>\",
      \"scope\":\"payment\",
      \"token_type\":\"Bearer\",
      \"expires_in\":300}",
  "scopes": [
    "payment"
  ],
  "subject": "testuser01",
  ...
}

  • Response if “Not kept” (i.e. invalidating the used RT) and “Disabled” (i.e. creating a new RT with a predefined duration)
Authlete issues a new RT (<refresh_token_2>) and sends it back to the authorization server. Its duration is set to 900 seconds.

{
  "type": "tokenResponse",
  "resultCode": "A053001",
  "resultMessage": 
   "[A053001] The token request (grant_type=refresh_token)
      was processed successfully.",
  "accessToken": "...",
  "action": "OK",
  "grantType": "REFRESH_TOKEN",
  "refreshToken": "<refresh_token_2>",
  "refreshTokenDuration": 900,
  "refreshTokenExpiresAt": ...,
  "responseContent": 
    "{\"access_token\":\"...\",
      \"refresh_token\":\"<refresh_token_2>\",
      \"scope\":\"payment\",
      \"token_type\":\"Bearer\",
      \"expires_in\":300}",
  "scopes": [
    "payment"
  ],
  "subject": "testuser01",
  ...
}

  • Response if “Not kept” (i.e. invalidating the used RT) and “Enabled” (i.e. creating a new RT with a remaining duration of the old RT)
Authlete issues a new RT (<refresh_token_2>) and sends it back to the authorization server. Its duration is not initialized. (an example omitted)
How did we do with this article?