Access Management 7.2.2

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. AM can issue refresh tokens during every OAuth 2.0/OpenID Connect grant flow, except for the implicit and the client credentials grant flows.

Why are refresh tokens useful?

Access tokens are short-lived because, if leaked, they grant potentially malicious users access to a resource owner’s resources. However, a client may need to access a protected resource for a period of time that exceeds 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 request a new access token, without further interaction from the resource owner. Although a malicious user with a compromised access token has access to the resource, a user who holds a refresh token must also have a compromised client ID and client secret to obtain an access token. This is because the client must authenticate to the token endpoint to obtain an access token using a refresh token.

Refresh tokens are long-lived by default. You can configure the lifetime of refresh 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 the OAuth2 provider attributes and the OAuth 2.0 client Advanced properties

You can configure a grace period, on the OAuth2.0 provider or per OAuth 2.0 client, during which refresh tokens can be reused. Refresh tokens can also be revoked (see /oauth2/token/revoke).

Configure AM to issue refresh tokens

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

When a new refresh token is issued, the old refresh token is deactivated.

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

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

  2. To let AM issue refresh tokens when refreshing access tokens, go 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:

    • Go to Realms > Realm Name > Applications > OAuth 2.0 > Client Name > Advanced.

    • In the Grant Types field, add the Refresh Token grant type.

    • Save your changes.

Refresh an access token

This procedure assumes the following configuration:

  • AM is configured as an OAuth 2.0 authorization server 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 AM 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.

If the OAuth 2.0 provider is configured for a subrealm rather than the Top Level Realm, you must specify it in the endpoint. For example, if the OAuth 2.0 provider is configured for the /alpha realm, use /oauth2/realms/root/realms/alpha/access_token.

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
}

The scope parameter is not required. By default, AM 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 AM has issued a new refresh token; the original refresh token is now inactive.