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

Background information

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 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 is configured to store access tokens and refresh tokens in the CTS store (server-side tokens). This is the default configuration. See Token storage location for further information.
• The replication purge delay is too long.

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

Finally, if none of these suggestions help, 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.

Recommendations

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

• Make sure any testing is realistic
• Reduce OAuth 2.0 access token and refresh token lifetimes
• Configure the OAuth 2.0 client to reuse access tokens
• Configure the OAuth 2.0 client to use a refresh token when access tokens expire
• Consider using separate OAuth 2.0 clients
• Reduce the replication purge delay

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.

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. You can set these lifetime values as follows in the AM admin UI:

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 AM to issue refresh tokens as explained in Configure AM to issue refresh tokens.

If you choose not to configure your client to use refresh tokens, you should ensure AM does 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

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

Best practice for configuring sessions in AM (All versions) to reduce the impact on the CTS store

Understanding CTS token types in AM

OAuth 2.0 grant flows

CTS configuration recommendations

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)