Using Refresh Tokens

When you obtain an OAuth access token, you can optionally choose to also obtain a refresh token. When your access token expires, the refresh token is used to obtain a new OAuth access token without requiring the user to reauthenticate (for example, without requiring a user to generate a new JWT user assertion).

Note: When you refresh a token, a new access token is generated using the default expiry of the scope you passed when requesting the initial token. The default expiry of urn:opc:idm:__myscopes__ is 3600 seconds and the default expiry of expiry of "urn:opc:idm:__myscopes__ urn:opc:resource:expiry" is 31556952 seconds. It is suggested that you only enable refresh tokens when using the urn:opc:idm:__myscopes__ scope if 31556952 seconds expiry is too high. You can optionally create a custom scope within your IDCS tenant to define an alternate expiry time for your access token when using refresh tokens.

To enable refresh tokens:

Edit the IDCS Confidential Application you created for JWT and enable the Refresh Token grant type. This step requires you to login to the IDCS Administration Console with a user assigned to the IDCS Administrator role.

To obtain a refresh token:

Add offline_access to the scope parameter when you call the IDCS /oauth2/v1/token endpoint to generate an OAuth access token. For example:

urn:opc:idm:__myscopes__ offline_access

The response will include a refresh token alongside the OAuth access token. For example:

{'access_token': '<OAUTH_ACCESS_TOKEN>', 'token_type': 'Bearer', 'expires_in': <TOKEN_EXPIRY>, 'refresh_token': '<REFRESH_TOKEN>'}

To use the refresh token:

You use the refresh token to generate a new access token once your existing token has reached its expiry.

Generate a new access token by calling your /oauth2/v1/token endpoint using the refresh_token grant type

Using your Client id and Client secret

POST https://<IDCSTenantURL>/oauth2/v1/token

Headers:
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic <BASE64ENCODED_CLIENTID:CLIENTSECRET>

Body (newlines for clarity):
  grant_type=refresh_token
  &refresh_token=<REFRESH_TOKEN>

Using a JWT client assertion

POST https://<IDCSTenantURL>/oauth2/v1/token

Headers:
  Content-Type: application/x-www-form-urlencoded

Body (newlines for clarity):
  grant_type=refresh_token
  &refresh_token=<REFRESH_TOKEN>
  &client_id=<IDCS_CONFIDENTIALAPPLICATION_CLIENTID>
  &client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
  &client_assertion=<BASE64ENCODED_JWT_CLIENT_ASSERTION>

To enable refresh tokens:

To obtain a refresh token:

To use the refresh token:

Using your Client id and Client secret

Using a JWT client assertion

Related Topics