Refresh Tokens

Refresh tokens are used to retrieve a new access token for a user without requiring the user to interactively authenticate again. A refresh token is typically long-lived (from days up to a month is common), but they enable the creation of short-lived (from minutes to hours) access tokens. This is good from security perspective since anyone that is in possession of an access token is allowed to call API:s that the token has access too and by giving them a short life-time the consequence of a stolen access token is less than if it is long-lived.

Get a refresh token

It is easy for the application to request a refresh token, since all that is necessary is to add the offline_access scope to the scope parameter list when making the authorization request.

Since it is a privileged operation to use a refresh token, the client must be configured to allow offline access. In client administration it is also possible to configure for how long a refresh token is valid and other settings.

Use a refresh token

The refresh token is used to retrieve a new access token (and/or ID token) for a user without re-authenticating the user. This should be done a short while before the access token expires (and not each time you need an access token) so that you always have an access token that are valid when calling the API.

To get a new access token, the refresh token is send to the token endpoint and the result is a token response containing a new access token, its expiration and potentially a new refresh token.

POST /connect/token
    client_id=client&
    client_secret=secret&
    grant_type=refresh_token&
    refresh_token=the_refresh_token

Security Consideration

Refresh tokens are extremally valuable (because they are long-lived) and must be carefully protected by the clients that are allowed to use them.

Refresh Token Rotation

By default Authway rotates the refresh token on each usage so that the refresh token only can be used once. This reduces the attack surface because there is a chance that a stolen token becomes unusable before the attacker have used it.

Since this is the default configuration for a client, it is important that the client takes this in consideration when using the refresh token. The client is responsible to synchronize the renewal between threads (so the refresh token isn’t used multiple times) and since the second use of a refresh token will result in a response with status code 400, it is a risk that the client invalidates the user session.

For .NET developers we recommend you to use Duende Access Token Management which has support for many token management tasks.