Skip to main content

Refresh Token Flow

This article describes what refresh tokens are and how they are used in SecureAuth.

What Refresh Token Flow Is

Refresh Token Flow can be utilized to exchange OAuth Refresh Tokens for Access Tokens to improve the users' experience in case the previous access token expires. In such a case, the user does not have to authenticate and consent again. A new token can have an identical or narrower scope.

By design, refresh tokens are long-lived, but they can also expire. Additionally, they are single-use only. Every time a refresh token is used to request access tokens, a new refresh token is issued and the previous token is invalidated.

Warning

Refresh tokens can feature a considerably long lifetime. Make sure you handle refresh tokens securely and prevent them from getting leaked. It is also possible to revoke a refresh token.

How Refresh Token Flow Works

An authorization grant call returns a refresh token along with an access token, when the request includes the scope parameter value set to offline_access.

The refresh token is provided to obtain a new access token by means of the refresh token grant flow.

The refresh token can be exchanged to the new access token only once. When the application requests a new access token, it also receives the next refresh token for later use.

Refresh_Token_Flow.svg

The example diagram above illustrates the interactions that occur during the refresh token grant flow.

  1. The client makes an authorization request.

  2. The authorization server issues an access token and a refresh token.

  3. The client requests protected resources from the resource server and submits its access token.

  4. The resource server validates the request and responds with requested resources.

    Result: The access token expires.

  5. The client requests protected resources with the same (expired) access token.

  6. The resource server validates the request. Since the access token is expired, the resource server responds with the Invalid token error.

    Tip

    At this point, without the use of refresh tokens, it would be required to authenticate the client again to obtain a new access token.

  7. The client makes a request to the /token endpoint and provides its refresh token as the value of the refresh_token parameter.

    Here's a sample call to the token endpoint with SecureAuth as an authorization server:

    curl --location --request POST "https://$TENANT_ID.$REGION_ID.authz.cloudentity.io/$TENANT_ID/$WORKSPACE_ID/oauth/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=$CLIENT_ID" \
--data-urlencode "client_secret=$CLIENT_SECRET" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "redirect_uri=$REDIRECT_URI" \
--data-urlencode "refresh_token=$REFRESH_TOKEN" \
--data-urlencode "code=$AUTHORIZATION_CODE"

    Upon the refresh token validation:

  8. Authorization server issues the new access token along with the new refresh token.

  9. The client requests protected resources from the resource server and submits the new access token it received in the previous step.

  10. The resource server validates the token and responds with requested resources.

SecureAuth comes with multi-tenant authorization server as a service that supports the Refresh Token Flow.

In SecureAuth, the following modifications are available for the refresh token:

  • Time-to-live: the period of the refresh token usage to issue a new access token. To configure TTL for your refresh token, go to Auth Settings > Tokens > TTL. It's recommended to set the TTL period to 30 days at maximum.

  • Token cycling is enabled by default. This technique reduces the risk of a refresh token misuse since it limits the window of opportunity for using such a token. However, sometimes token cycling must be disabled, for example, to meet the Open Banking CDR requirements. To disable token cycling, go to Auth Settings > Advanced and select Disable refresh token cycling.

In this section: