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 by sending a previously issued refresh token. The authorization server checks if the refresh token is valid, and then issues the new access token and sends it back to the client.

There are two choices for handling the used refresh token; keeping it valid for the next token refresh, or making it invalid to avoid reusing.

You can configure Authlete to support either one of choices. This article describes these characteristics for each one.

Invalidating the used refresh token


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

Available duration for refreshing an access token gets extended at every time refresh tokens are renewed.

Keeping the used refresh token valid


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

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


Configuration


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

Examples


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

  • Request
An authorization server makes a request to Authlete's /auth/token API to process the token request including the refresh token. 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 “Not kept” (i.e. invalidating the used refresh token)
Authlete issues a new refresh token (<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 “Kept” (i.e. keeping the used refresh token valid)
Authlete sends back the same refresh token 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",
  ...
}
How did we do with this article?