Use refresh tokens

This topic describes how to use and manage OpenID Connect (OIDC) refresh tokens.

Overview

Refresh tokens are credentials used to obtain access tokens. The authorization server issues the refresh tokens to obtain new access tokens when access tokens expire or become invalid. Sometimes the refresh tokens can be used to obtain additional access tokens with narrower scopes.

Refresh tokens are generally opaque to the client. Refresh tokens are optional and are only intended to be used by the authorization server and not sent to the resource server.

How it works

  1. The client requests an authorization grant.

  2. The authorization server authenticates the user, and the client and issues access and refresh tokens to the client.

  3. The client requests a protected resource by passing the access token to the resource server.

  4. The resource server validates the access token and gives the client access to the protected resource.

  5. The client makes another request to the resource server with the same access token.

  6. The resource server validates the access token and responds with an invalid token error.

  7. The client requests the authorization server for a new access token by exchanging the refresh token.

  8. The authorization server issues access and, optionally, refresh tokens.

Use refresh tokens in CyberArk Identity

To issue refresh tokens in CyberArk Identity, you have to enable the issuing of refresh tokens on the Admin Portal as shown below:

Once this is enabled, the client receives refresh tokens in the /token endpoint. The response of the token endpoint is as follows:

{
    "id_token": "eyJhbGciOiJSUzI1… ",
    "refresh_token": "2k1rYZV…",
    "access_token": "eyJhbGciOi… ",
    "token_type": "Bearer",
    "expires_in": 18000,
    "scope": "<scope>"
}

Exchange a refresh token for an access token

The client application sends the token request with the refresh to the authorization server with grant_type as refresh_token.

POST {tenant_url}/oauth2/token/{application_id}
{
    'grant_type': 'refresh_token',
    'client_id': ‘client ID’',
   'client_secret': 'client secret',
    ‘refresh_token’: ‘NkTkDHFz.Dos5qUi...'
}

The authorization server responds to the client application with an access token and then the user is logged in to the client application.

{
    'access_token': 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsMN0Y5NkVERjc5MEYx...',
     'token_type': 'Bearer',
    'expires_in': 18000,
    'scope': ''
}

Validate refresh tokens

You can validate a refresh token using the /OAuth2/Introspect URL.

Store refresh tokens

For best practices for storing tokens, see Token storage.

Set the token expiry

You can set the expiry of a refresh token on the OIDC custom app as shown below:

The default value is 365 days. Refresh tokens are typically long-lasting credentials.