Table of Contents
“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:
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.
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.
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.
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).
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)
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.
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.
You can choose “Linked
” or “Not Linked
” at “Token Expiration Link
” section regardless of your choices above.
The following examples are a sample request and responses when a client makes a token request using a RT (< refresh_token_1 > ).
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 >
"}'
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",
...
}
Authlete sends back the same RT as being used (< refresh_token_1 > ) to the authorization server. Its duration is initialized. (an example omitted)
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",
...
}
Authlete issues a new RT (< refresh_token_2 > ) and sends it back to the authorization server. Its duration is not initialized. (an example omitted)