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.

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 AM 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 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. Note that, when a new refresh token is issued, the old refresh token is deactivated.

  1. To enable AM 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 AM to issue refresh tokens.

  2. (Optional) To enable AM 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:

  • AM is configured as an OAuth 2.0 authorization server in the Top Level Realm with the following configuration:

    • Issue Refresh Tokens is enabled.

    • Issue Refresh Tokens on Refreshing Access Tokens is enabled.

    • The token plugin is configured in the Response Type Plugins field.

    • 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

    • Response Types: token

    • 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 /customers realm, then use /oauth2/realms/root/realms/customers/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/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, 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.

Read a different version of :