Skip to main content

​
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 four choices for handling the used RT:
  • 1-1: Keeping the RT valid for the next token refresh and not resetting the duration of the RT,
  • 1-2: Keeping the RT valid for the next token refresh and resetting the duration of the RT,
  • 2-1: Making the RT invalid and creating a new RT with a predefined duration, or
  • 2-2: Making the RT invalid and creating a new RT with a remaining duration of the old RT.
In addition to the options above, Authlete provides a Token Expiration Link feature that limits duration of access tokens within the remaining duration of its corresponding refresh token. You can configure Authlete to support either one of four choices and the link feature. This article describes these characteristics.
The feature of “2-2: Making the RT invalid and creating a new RT with a remaining duration of the old RT” is available in Authlete version 2.1 and later.
The feature of “1-2: Keeping the RT valid for the next token refresh and resetting the duration of the RT is available in Authlete version 2.2 and later.
The Token Expiration Link feature is available in Authlete version 2.2 and later.

​
1-1: Keeping the RT valid for the next token refresh and not resetting the duration of the RT

On a token refresh request from a client with an RT (rt1), an authorization server sends a new AT (at2) and the submitted RT (rt1) back to the client. The RT (rt1) will remain valid so that the client can reuse the RT (rt1) in the next token refresh request as long as its duration remains. 
The validity period of the RT (rt1) won’t be changed on each token refresh.\ refreshing-refresh-tokens-02

​
1-2: Keeping the RT valid for the next token refresh and resetting the duration of the RT

On a token refresh request from a client with an RT (rt1), an authorization server sends a new AT (at2) and the submitted RT (rt1) back to the client. The RT (rt1) will remain valid so that the client can reuse the RT (rt1) in the next token refresh request as long as its duration remains. Available duration of RT (rt1) is reset to the initial value on each token refresh. As a result, the available duration of RT (rt1) will be extended over the multiple requests.refreshing-refresh-tokens-04_en

​
2-1: Making the RT invalid and creating a new RT with a predefined duration

On a token refresh request from a client with an RT (rt1), an authorization server sends a new AT (at2) and a new RT (rt2) back to the client. The submitted RT (rt1) will be invalidated so that the client can no longer reuse the RT (rt1) in the next token refresh request.
Available duration of RT (rt2, rt3, …) will be set to the initial value. As a result, the total available duration of the RT (rt2, rt3, …)  gets extended more than the initial value of the RT (rt1).refreshing-refresh-tokens-01

​
2-2: Making the RT invalid and creating a new RT with a remaining duration of the old RT

On a token refresh request from a client with an RT (rt1), an authorization server sends a new AT (at2) and a new RT (rt2) back to the client. The submitted RT (rt1) will be invalidated so that the client can no longer reuse the RT (rt1) in the next token refresh request.
Available duration of RT (rt2, rt3, …) is set to the remaining duration of the first RT (rt1). As a result, the total available duration of the RT (rt2, rt3, …) is limited to the duration of the first RT (rt1)\ refreshing-refresh-tokens-03 On a token refresh request from a client with an RT (rt), an authorization server checks if the remaining duration of the RT is shorter than the default duration of the AT. If it is true, Authlete issues a new AT whose duration is linked to the remaining duration of the RT.\ token-duration-link

​
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. There are additional settings for each choice.
  • When specifying “Kept,” you can further choose “Enable” or “Disable” at “Refresh Token Duration Reset” section.
  • When specifying “Not kept,” you can further choose “Enabled” or “Disabled” at  “Refresh Token Duration Takeover” section.
You can choose  “Linked” or “Not Linked” at “Token Expiration Link” section regardless of your choices above.Screen_Shot_2023-02-01_at_6

​
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) and “Disabled” (i.e. reset the duration of the RT) are specified
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 “Kept” (i.e. keeping the used RT valid) and “Enabled” (i.e. reset the duration of the RT) are specified
Authlete sends back the same RT as being used (< refresh_token_1 >) to the authorization server. Its duration is initialized. (an example omitted)
  • Response if “Not kept” (i.e. invalidating the used RT) and “Disabled” (i.e. creating a new RT with a predefined duration) are specified
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) are specified
Authlete issues a new RT (< refresh_token_2 >) and sends it back to the authorization server. Its duration is not initialized. (an example omitted)