Offline access also known as the Refresh Token grant type is used by applications to exchange a refresh token for an access token when the access token has expired. This allows applications to continue to have a valid access token without interaction with the user.

Offline access is only supported for Web and native applications. To enable it, you must first check the Offline Access checkbox for your application under Details tab.

The second step for having offline access support is to use offline_access scope in the authentication/authorization request. At the end of the authorization, your application will also obtain a refresh_token that can be used for obtaining a new access token.

Refreshing Access Tokens

To refresh a token, using the refresh_token you already got during authorization, make a POST request to the /connect/token endpoint, providing the following parameters:

Sample request:

curl --request POST --url https://connect.visma.com/connect/token --header 'content-type: application/x-www-form-urlencoded' --data 'client_id=demoapp&client_secret=SECRET&grant_type=refresh_token&refresh_token=7990438c99d8158108ab225a4c21f3156ed2b8596a46195ae9fa7c3e88d61e65'

If successful, this call will return a neatly packaged token that will contain the following fields:

{ 
"id_token": "<tokenstring>",
 "access_token": "<tokenstring>",
 "expires_in": 3600, 
"token_type": "Bearer", 
"refresh_token": "<newrefreshtokenstring>" 
}

Native applications do not use a client_secret in the authentication/authorization process therefore client_secret is not required when refreshing access tokens.

In order to revoke a refresh token, please refer to token revocation documentation.

Refresh Token security considerations

Refresh Tokens are a high-value target for attackers, because they typically have a much higher lifetime than Access Tokens. The following techniques can be used to reduce the attack surface of Refresh Tokens.

Consent

It’s a good idea to ask for user consent. This way your app makes the user aware of what’s happening with offline access.

Sliding expiration

Refresh Tokens usually have a (much) longer lifetime than an Access Token. You can reduce the exposure though by also adding a sliding lifetime on top of the absolute lifetime. This allows for scenarios where a Refresh Token can be silently used if the user is regularly using the client, but needs a fresh authorize request, if the client has not been used for a certain time. In other words, they auto-expire much quicker without potentially interfering with the typical usage pattern. Use the "But will expire if not used in ... days" option to enable this.

One-time Refresh Tokens

Another option is rotating the Refresh Tokens on every usage. This also reduces the exposure, and has a higher chance to make older Refresh Tokens (e.g. ex-filtrated from some storage mechanism or a network trace/log file) unusable.

Replay detection

When one-time tokens are used, replay detection is enabled. This means, that if the same Refresh Token is used more than once, all access to the client/user combination is revoked. The downside of this approach is, that you might have more scenarios where a legitimate Refresh Token becomes unusable – e.g. due to network problems while refreshing them.