Token Exchange

Token exchanbge enables client applications to request and obtain security tokens (such as access tokens) from the eHealth authorization server.

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:

The user logs in and gets back an AT and an 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 for the longest. The validity of old RTs can not be guaranteed, as the AS, at some point in the future, may be configured to revoke RTs 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:

Attempt requesting new AT after session expires using RT2

Error response

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 a 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 user's active session expires or a server restarts. 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 an 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. Otherwise unused offline tokens will pile up on the AS.