Configuring timeouts for access tokens and refresh tokens

Configure timeout values for the access tokens and refresh tokens for user registries.

About this task

IBM® API Connect supports the use of access tokens and refresh tokens for user registries that authenticate users of the Cloud Manager, the API Manager, and the Developer Portal.

Access tokens allow users to sign in and remain logged in for a specified amount of time (the timeout period). Refresh tokens allow the access token to be renewed automatically without requiring the user to sign in again. Access tokens are configured by default, and you can modify the timeout setting. Refresh tokens are disabled by default but are configured with a default timeout when you enable them.

Refresh tokens, when enabled, are generated every time an access token is created. Refresh tokens can be used to obtain a new access token without having to prompt a user to re-login. If you enable the use of refresh tokens, then when the token expires it is refreshed automatically in the background so that the user can continue working without interruption. When the user logs out, the refresh token is revoked and the application can no longer use it.

Note: If users log in with non-OIDC user registries, the use of refresh tokens is supported in API Manager, API Designer, the Developer Portal, and the CLI Toolkit. When the refresh token expires, the user is always redirected to the login page.
If users log in with OIDC user registries:
  • The use of refresh tokens is supported only in the Developer Portal and the CLI Toolkit
  • If the OIDC providers do not support refresh tokens, API Connect will not issue a refresh_token, regardless of the setting of refresh_token_enabled in the cloud settings.
  • For more information about OIDC configuration, see Configuring an OIDC user registry in Cloud Manager.

You can configure access tokens and refresh tokens using the Cloud Manager UI, or the Toolkit CLI.

Using the UI to configure tokens

Configure timeout settings for access tokens and refresh tokens in the Cloud Manager Settings pages.

Procedure

  1. Click Cloud Settings icon in the navigation pane.
  2. Configure the timeout for access tokens:
    1. On the Onboarding page, click Edit next to Access Token Time to Live.
    2. To specify a timeout value, select or type an integer value in the Number field and then choose a unit of time (Seconds, Minutes, or Hours) in the Unit field.
    3. Click Save.
  3. Configure the timeout for refresh tokens:
    1. On the Onboarding page, click Edit next to Refresh Token Time to Live.
    2. To specify a timeout value, select or type an integer value in the Number field and then choose a unit of time (Seconds, Minutes, or Hours) in the Unit field.
    3. Click Save.

Using the CLI to configure tokens

Use the Toolkit CLI to configure timeout settings for access tokens and refresh tokens.

About this task

Use the following properties to specify refresh tokens for cloud settings:

  • access_token_expires_in

    Integer. Represents the expiration time, in seconds, for access tokens issued by API Connect.

  • refresh_expires_in

    Integer. Represents the expiration time, in seconds, for refresh tokens issued by API Connect. Must be greater than access_token_expires_in.

  • refresh_token_enabled

    Boolean. Disabled by default. To enable, set to true. When enabled, generates a refresh_token field in the response to the /token API call.

The following extract from a cloud settings file shows example settings for these properties:

"type": "cloud_setting",
"api_version": "2.0.0",
"name": "cloud-setting",
"access_token_expires_in": 28800,
.
.
.
"refresh_expires_in": 57600,
"refresh_token_enabled": false,
.
.
.

Use the toolkit CLI (apic) to update the cloud settings with new values for the properties. You can either specify values as command line arguments, or enter them manually in a configuration file as explained in Using the CLI to modify cloud settings.