Refresh Token: Concept, Purpose, Way It Works
Get familiar with the concept of the refresh token. Learn why and when it is useful. Check how to use it securely.
What Refresh Token Is
Refresh tokens are long-lived tokens used to acquire a new access token when the present access token gets invalid or expires. They enable the client to get a new access token without prompting the user.
The refresh token is an string of characters that represents the authorization granted to the client by the resource owner. Refresh tokens are exchanged between the client and the authorization server and never sent to the resource server.
Refresh tokens are issued to the client by the authorization server. Issuing a refresh token is optional at the discretion of the authorization server. If the authorization server issues a refresh token, it is included when issuing an access token.
Enable Refresh Tokens in SecureAuth
If you want SecureAuth to issue refresh tokens, you need to configure your workspace and application settings accordingly. See the video for the guidelines on how to enable the refresh token grant, verify the offline access scope, and configure TTL for your refresh token. Alternatively, check the instructions in Configure workspace settings and Configure client settings.
Configure Workspace Settings
In SecureAuth, navigate to the workspace where your application can be accessed and select Settings from the sidebar.
Open the Authorization view, navigate to Allowed grant types, select the Refresh token checkbox, and save your changes.
Configure Client Settings
In SecureAuth, navigate to the workspace where your application can be accessed for configuration, select Applications > Clients from the sidebar, open the application you want to configure, and go to its OAuth view.
Navigate to Grant types, add refresh_token from the drop-down list, and save your changes.
Open the Scopes view, select the Profile service to expand the list of available scopes, and make sure that the offline access scope is enabled.
Configure TTL
Refresh tokens are long-lasting artifacts. They are long-lived tokens with TTLs up to a few years.
In SecureAuth, there are TTLs for refresh tokens predefined per workspace (authorization server). You can modify them by entering a particular workspace and navigating to Auth Server > Tokens > Time to Live Settings > Refresh token TTL.
Way it Works
The client can request a refresh token early in the process of retrieving an access token. For details on the authorization grant flow featuring the refresh token, see Refresh token grant.
Note
Make sure your refresh tokens are not stored in the browser local storage unless you have the refresh token rotation set up.