How To
ForgeRock Identity Platform
ForgeRock Identity Cloud

How do I improve performance with OAuth 2.0 tokens in Identity Cloud and AM 6.5.x, 7.x?

Last updated Sep 14, 2021

The purpose of this article is to provide assistance if you experience performance issues in Identity Cloud or AM associated with OAuth 2.0 tokens. This will likely manifest as degraded performance in OAuth 2.0 related services. This information applies when you are using the grant-set storage scheme for OAuth 2.0 tokens in the CTS store; this storage scheme is always used in Identity Cloud and is the recommended scheme in later versions of AM.

Background information

Identity Cloud uses the grant-set scheme for storing OAuth 2.0 tokens in the CTS store, and it is the recommended storage scheme in later versions of AM.

The grant-set scheme groups multiple authorizations for a given OAuth 2.0 client (Client Credentials flow) or client and resource owner pair (other OAuth 2.0 flows), and stores them in a single grant-set (OAUTH2_GRANT_SET) entry. This scheme reduces the amount of data stored in the CTS by removing duplication and reduces the number of operations to the CTS.

When clients are configured correctly, this is a much more efficient storage scheme for OAuth 2.0 tokens. However, you can experience performance issues when a grant-set entry grows too large and continues to see high volumes of activity.

The following factors can contribute to a large grant-set entry and may lead to degraded performance: 

  • You have long-lived tokens, which means they don't expire quickly. The expiration date (coreTokenExpirationDate) is updated each time a token is added, and although Identity Cloud or AM will clean up expired tokens, it is possible that the number of tokens being issued will exceed the number being cleaned up when there is a steady flow of tokens with a long lifetime.
  • You have single-use tokens. This means the OAuth 2.0 client issues new tokens for each request, which increases the amount of activity.
  • You have a lot of activity focused on a single OAuth 2.0 client, meaning a grant-set contains a lot of active tokens.
  • AM only: AM is configured to store access tokens and refresh tokens in the CTS store (CTS-based tokens). This is the default configuration. See About Token Storage Location for further information.
  • AM only: The replication purge delay is too long.

The following section provides specific recommendations for Identity Cloud and AM to improve performance. Bear in mind that the ideal OAuth 2.0 client should reuse their access tokens rather than re-authenticating for every API call and only refresh tokens when needed. 

Finally, if none of these suggestions help in AM, you can revert to the one-to-one scheme instead. See OAuth 2.0 CTS Storage Scheme for further information. If you do change the storage scheme, existing tokens will continue to use the grant-set storage scheme until they expire and any newly issued tokens will use the one-to-one scheme.


You should follow these recommendations to improve performance with OAuth 2.0 tokens:

Make sure any testing is realistic

You must make sure any load testing of expected token volumes is realistic and sustained over several days. For example, don't try load testing OAuth 2.0 with only one user and one OAuth 2.0 client. This type of test will cause the grant-set to grow excessively and won't yield meaningful results for you to work with.

Additionally, when you do any performance testing in Identity Cloud, it is important that you do it in your Staging environment not your Development environment; the Development environment is not scaled for high availability and performance, whereas the Staging environment is scaled to match your Production environment to facilitate realistic testing.

Reduce OAuth 2.0 access token and refresh token lifetimes

You can reduce the OAuth 2.0 access token and refresh token lifetimes to make them expire quicker. You need to balance usability and performance when setting token lifetimes, and you will need to test any new settings in your pre-production environments (Staging in Identity Cloud). You can set these lifetime values as follows: 

  • Identity Cloud Admin UI
    1. Navigate to Applications and click the name of your OAuth 2.0 client.
    2. Under General Settings, click Show advanced settings and select the Token Lifetimes tab.
    3. Set the Access token and Refresh token lifetimes in seconds.
    4. Click Save.
  • AM console
    1. Navigate to Applications > OAuth 2.0 > Clients and click the name of your OAuth 2.0 client.
    2. On the Core tab, set the Access token and Refresh token lifetimes in seconds.
    3. Click Save Changes.

Configure the OAuth 2.0 client to reuse access tokens

You can configure your OAuth 2.0 client to cache access tokens and reuse them until they expire rather than getting a new access token every time you make a call. This is the recommended configuration and is much more efficient but does require development work in your client application. Developing client applications is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Configure the OAuth 2.0 client to use a refresh token when access tokens expire

Similarly, you could consider using refresh tokens when the access token expires. You will need to make changes to your client application to make use of refresh tokens and also configure Identity Cloud or AM to issue refresh tokens as explained in To Configure Identity Cloud to Issue Refresh Tokens or To Configure AM to Issue Refresh Tokens

If you choose not to configure your client to use refresh tokens, you should ensure Identity Cloud or AM do not issue them, as otherwise, the grant lifetime will be longer than needed. 

Consider using separate OAuth 2.0 clients

If you are using the same OAuth 2.0 client for multiple services, you could consider using one client per service to reduce the number of tokens being issued per client. This in turn would reduce the size of the grant-set and improve performance.

Reduce the replication purge delay (AM only)

A grant-set entry contains ds-sync-hist operational attributes among other things. These attributes record a history of all changes (adds, deletes and modifies) to the grant-set entry. These attributes are retained per the replication purge delay (three days by default), so a grant-set entry size is in part determined by the length of the replication purge delay.

You can reduce the replication purge delay for the CTS store to reduce the size of the grant-set entry, but you must ensure it is set appropriately to keep data long enough for replication and data recovery purposes. Information about replication changes is permanently gone once it has been purged from the changelog. See How do I control how long replication changes are retained in DS (All versions)? and CTS Backups and DS Replication Purge Delay for further information.

See Also

Identity Cloud


Related Issue Tracker IDs

OPENAM-16840 (High volume of client credential grants causes issues for CTS grant sets)

OPENDJ-8145 (Avoid GrantSet ds-sync-hist attributes creating a performance problem)

OPENDJ-7476 (Add a histogram monitoring metric which records operations which target large entries)

Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.