Refresh Tokens

Refresh tokens (RFC 6749) are a type of token that can be used to obtain a new access token that may have identical or narrower scopes than the original. Identity Cloud can issue refresh tokens during every OAuth 2.0/OpenID Connect grant flow except for the Implicit and the Client Credentials grant flows.

Access tokens are short-lived because, if leaked, they grant potentially malicious users access to the resource owner resources. However, clients may need to access the protected data for periods of time that exceed the access token lifetime or when the resource owner is not available. In some cases, it is unreasonable to ask for the resource owner's consent several times during the same operation.

Refresh tokens solve this problem by letting clients ask for a new access token without further interaction from the resource owner. While a potentially malicious user compromising an access token has access to the resource owner resources, one that holds a refresh token also needs to compromise the client ID and the client secret to be able to get an access token, since the client needs to authenticate to the token endpoint to obtain an access token using the refresh token.

Refresh tokens are long-lived by default, and Identity Cloud lets you configure the lifetime of the tokens in the OAuth 2.0 Provider settings, or in each client. By default, the configuration of the OAuth 2.0 Provider is used. For more information, see Advanced Properties and "OAuth2 Provider".

Refresh tokens can also be revoked. For more information, see "/oauth2/token/revoke").

Tasks:

To Configure Identity Cloud to Issue Refresh Tokens

Identity Cloud can issue refresh tokens during the following actions:

  • When issuing an access token to the client after a successful OAuth 2.0 grant flow.

  • When the client successfully uses a refresh token to obtain a new access token. Note that, when a new refresh token is issued, the old refresh token is deactivated.

  1. To enable Identity Cloud to issue refresh tokens at the same time the access token is issued, navigate to Realms > Realm Name > Services > OAuth2 Provider > Core, and enable Issue Refresh Tokens.

    Note that you configure refresh tokens at realm level. Consider carefully the types of clients registered to the realm before configuring Identity Cloud to issue refresh tokens.

  2. (Optional) To enable Identity Cloud to also issue refresh tokens when refreshing access tokens, navigate to Realms > Realm Name > Services > OAuth2 Provider > Core, and enable Issue Refresh Tokens on Refreshing Access Tokens.

  3. Save your changes.

  4. To configure a client to use the Refresh Token grant flow perform the following steps:

    1. Navigate to Realms > Realm Name > Applications > OAuth 2.0 > Client Name > Advanced.

    2. On the Grant Types field, add the Refresh Token grant type.

    3. Save your changes.

To Refresh an Access Token

This procedure assumes the following configuration:

  • Identity Cloud is configured as an OAuth 2.0 authorization server in the with the following configuration:

    • Issue Refresh Tokens is enabled.

    • Issue Refresh Tokens on Refreshing Access Tokens is enabled.

    • The Refresh Token grant type is configured in the Grant Types field.

    For more information, see Authorization Server Configuration.

  • A confidential client called myClient is registered in Identity Cloud with the following configuration:

    • Client secret: forgerock

    • Scopes: write read

    • Grant Types: Authorization Code Refresh Token

Perform the steps in the procedure to refresh an access token:

  1. The client obtains an access token and a refresh token using the Authorization Code Grant flow. For more information, see "Authorization Code Grant".

    The example assumes the refresh token is qz1qx-9AYOkRp3AWcCZULvPitpM.

  2. The client makes a POST call to the authorization's server token endpoint, specifying, at least, the following parameters:

    • grant_type=refresh_token

    • refresh_token=your_refresh_token

    For more information about the parameters supported by the /oauth2/access_token endpoint, see "/oauth2/access_token".

    Confidential clients can authenticate to the OAuth 2.0 endpoints in several ways. This example uses the following form parameters:

    • client_id=your_client_id

    • client_secret=your_client_secret

    For more information, see OAuth 2.0 Client Authentication.

    You must specify the realm in the endpoint. For example, if the provider is configured for the /alpha realm, then use /oauth2/realms/root/realms/alpha/authorize.

    For example:

    $ curl --request POST \
    --data "grant_type=refresh_token" \
    --data "refresh_token=qz1qx-9AYOkRp3AWcCZULvPitpM" \
    --data "client_id=myClient" \
    --data "client_secret=forgerock" \
    --data "scope=read" \
    "https://openam.example.com:8443/openam/oauth2/realms/root/realms/alpha/access_token"
    {
       "access_token":"y-C_A1RKJIg-BUlKhp--kv5Iywk",
       "refresh_token":"qdqVnFJK8FjiQAjYMaBuUY6z_HU",
       "scope":"read",
       "token_type":"Bearer",
       "expires_in":3599
    }

    Note that the scope parameter is not required. By default, Identity Cloud will issue an access token with the same scopes of the original. This example is restricting the new access token to the read scope.

    Also note that Identity Cloud has issued a new refresh token; the original refresh token is now inactive.

Read a different version of :