Refresh tokens (RT) are used to obtain new access tokens (AT) from the Authentication Server (AS). Refresh tokens are long-lived while access tokens are short-lived. This allows for long-lived sessions that can be terminated if necessary. The typical flow is:
User logs in and gets back an AT and a RT
The application detects that the AT is expired or that a different AT is required
The application uses the RT to obtain a new AT and a new RT that replaces the old RT
Repeat 2 and 3 until the RT or the session expires
After the RT or the session expires, the user must authenticate again
By default RT’s expire after 30 minutes of inactivity, while the session can be kept alive for 10 hours by exchanging tokens at least every 30 minutes, thereby getting a new RT.
It is highly recommended that the application always uses the RT from the latest exchange, as this will be valid the longest. The validity of old RT’s can not be guarantied, as the AS, at some point in the future, may be configured to revoke RT’s after a certain number of uses.
Example:
Login request (direct grant):
POST /auth/realms/ehealth/protocol/openid-connect/token HTTP/1.1 grant_type=password& username=cgi_clinical_b& password=Test1234& client_id=oio_mock
Response with AT1 and RT1:
HTTP/1.1 200 OK
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgO...",
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgO...",
"token_type": "bearer",
"not-before-policy": 1587013531,
"session_state": "c9b7eeb5-4d59-4016-9626-1e3587bfff35",
"scope": "profile oio_custom email"
}
Requesting new AT using RT1:
POST /auth/realms/ehealth/protocol/openid-connect/token HTTP/1.1 grant_type=refresh_token& client_id=oio_mock& refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCIgO...
Response with AT2 and RT2:
HTTP/1.1 200 OK
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgO...",
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgO...",
"token_type": "bearer",
"not-before-policy": 1587013531,
"session_state": "c9b7eeb5-4d59-4016-9626-1e3587bfff35",
"scope": "profile oio_custom email"
}
Attempt requesting new AT after session expires using RT2
POST /auth/realms/ehealth/protocol/openid-connect/token HTTP/1.1 grant_type=refresh_token& client_id=oio_mock& refresh_token=eyJhbGciOiJIUzI1NiIsInR5cCIgO...
Error response
HTTP/1.1 400 Bad Request
{
"error": "invalid_grant",
"error_description": "Session not active"
}
Offline Tokens
Offline access is a feature described in OpenID Connect specification . The idea is that during login, your client application will request an Offline token instead of a classic Refresh token. The application can save this offline token in a database or on disk.
The difference between a classic Refresh token and an Offline token is, that an offline token will never expire by default. The offline token is valid even after a users active session expires or server restart. However by default the offline token expires after 30 days if not used.
The flow for using Offline tokens is the same as the one for classical Refresh tokens, except for the first step.
The client can request an offline token by adding the parameter scope=offline_access when sending authorization request to the AS.
The parameter is added to the URL when using the standard browser authentication flow:
https://auth.com/secured?scope=offline_access
Or to the request body when using the direct grant flow.
It is only recommended to use offline access if you intend to store the Offline token for later use. Else unused offline tokens will pile up on the AS.