The Refresh Token is defined by the OAuth2 specification.

An Access Token is a string representing credentials used to obtain access tokens. The Refresh Token is typically used to obtain a new access token when the current access token, issued to the client, becomes invalid or expires. The purpose of the Refresh Token is to allow for short lived Access Tokens (more secure) and at the same time avoid the end-user having to re-authenticate frequently. Hence, the Client Credentials grant does not issue a refresh token. It makes no sense, as the client can simply get another token with the same client credentials.  If the authorization server issues a refresh token, it is included when issuing an access token.

In contrast to the ID Token, the string is usually opaque to the client. Neither the OAuth2 or the OIDC specifications define any format for the token.

The OAuth2 specification further underlines that "Unlike access tokens, refresh tokens are intended for use only with authorization servers and are never sent to resource servers.". The Buypass implementation of the Refresh Token is is represented using JSON Web Token (JWT) (by-value token). This means that the token can also easily be decoded locally.

However: The claims  within the Refresh Token is not considered part of the supported OIDC Authentication API from Buypass. Hence, changes in the refresh token may occur without further notice. Buypass encourage use of the claims provided in the Refresh Token only for test and debugging purposes.

Token lifespan

As described in Access Token, the specification states "Access Tokens might not be revocable by the Authorization Server. Access Token lifetimes SHOULD therefore be kept to single use or very short lifetimes.". It further states that "If ongoing access to the UserInfo Endpoint or other Protected Resources is required, a Refresh Token can be used. The Client can then exchange the Refresh Token at the Token Endpoint for a fresh short-lived Access Token that can be used to access the resource.".

As the Refresh Token can be used to get a ned Access Token, it needs to be protected in the same way as an Access Token. In the same way as for Access Tokens, the longer the token lives, the higher the risk of compromise is. In other words, if the Refresh Token somehow leaks (in a log, in the calling system or in the receiving service), the "window of opportunity" for an attacker increases with the token lifetime.

The main difference between a self contained Access Token and a Refresh Token is that the Refresh Token can be revoked. The client must send the Refresh Token to the Authorization Server to get an Access Token. Hence if the token is revoked, a new Access Token will not be issued.

In summary, the Refresh Token lifetimes and max reuse (how many times the same Refresh Token can be used without getting a new one) need to be considered carefully and depends on the security/risk level of the associated Security Domain.

Example of decoded Refresh Token

{
  "jti": "e167185c-3047-493d-9385-d16e052152c4",
  "exp": 1558530547,
  "nbf": 0,
  "iat": 1558528747,
  "iss": "https://auth.test.buypass.no/auth/realms/SECURITYDOMAIN",
  "aud": "https://auth.test.buypass.no/auth/realms/SECURITYDOMAIN",
  "sub": "f:22857cc7-c9f2-45be-94a5-026b3afd7e3b:15089100213",
  "typ": "Refresh",
  "azp": "oidc-client",
  "nonce": "v0PcxHETtufciXMtv3nhC9zaoisXfW_5-T4eQ_ECWYc",
  "auth_time": 0,
  "session_state": "2ce89f97-0126-4a8d-9fd4-bc581f9e87d1",
  "scope": "openid profile bpid email"
}