Authorization Basics

4 mins read

Refresh Token Flow

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

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.

Elevate Users' Experience Using Refresh Tokens

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

Launch OAuth Server
Learn More

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.

[mermaid-begin]
sequenceDiagram autoNumber participant Client application participant Resource server (API) participant Authorization server Client application-->>Authorization server: Authorization request activate Client application activate Authorization server Authorization server->> Client application: Access token + refresh token deactivate Authorization server loop Note over Client application,Resource server (API): Valid access token Client application->>Resource server (API): Request resources with an access token activate Resource server (API) Resource server (API)->>Client application: Respond with requested resources end alt Note left of Client application: Access token is no longer valid Client application--XResource server (API): Request resources with an access token Resource server (API)->>Client application: Invalid token error deactivate Resource server (API) else Client application->>Authorization server: Refresh token activate Authorization server Note right of Authorization server: Validate refresh token Authorization server->>Client application: New access token + refresh token deactivate Authorization server end loop Client application->>Resource server (API): Request resources with the new access token activate Resource server (API) Resource server (API)->>Client application: Respond with requested resources deactivate Resource server (API) deactivate Client application end

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.

    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.

    Sample call to the token endpoint with Cloudentity 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.

Try it now

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

In Cloudentity, 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.

Launch OAuth Server
Learn More
Updated: Sep 8, 2023