HomeProduct documentationGitHubCyberArk developer community

Refresh tokens

Suggest Edits

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.

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

How does it work?

1227
  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. 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.

Refresh tokens in CyberArk Identity

To issue refresh tokens in CyberArk Identity, the admin has to enable issuing of refresh tokens on the admin portal as below:

634

Once enabled, the client receives refresh tokens in the "/token" endpoint. The response of the token endpoint will be as below:

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

Exchange refresh token for 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 a refresh token

The refresh token can be validated using the introspect URL.

Storing refresh tokens

The most secure way to store the access tokens is on the server side for web applications and SPAs.

For native mobile apps, store tokens in the OS's secure storage and limit access to that storage. For example, leverage KeyStore for Android and KeyChain for iOS.

Refresh token expiry

The admin can set the refresh token expiry on the OIDC custom app as below:

634

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

👍

CyberArk Identity SDKs to implement and store refresh tokens

CyberArk Identity provides SDKs to integrate refresh token functionality into your applications and store the tokens securely

Updated 4 months ago