PingAM 7.5.1

Core Token Service (CTS)

These pages describe how to configure the Core Token Service, and how to manage the tokens stored in it.

Deployment architecture

Choose the best architecture for your deployment.
Configure a dedicated CTS store

Prepare a DS instance to host a dedicated CTS token store.
Manage tokens

Learn how to encrypt and/or compress tokens.
Manage expired CTS tokens

Configure how CTS tokens are pruned after they reach their maximum time-to-live.

Name changes for ForgeRock products

Product names changed when ForgeRock became part of Ping Identity.

The following name changes have been in effect since early 2024:

Old name New name

ForgeRock Identity Cloud

PingOne Advanced Identity Cloud

ForgeRock Access Management

PingAM

ForgeRock Directory Services

PingDS

ForgeRock Identity Management

PingIDM

ForgeRock Identity Gateway

PingGateway

Learn more about the name changes in New names for ForgeRock products in the Knowledge Base.

CTS overview

The Core Token Service (CTS) provides generalized, persistent, and highly available storage for sessions and tokens. AM uses CTS as the authoritative source for server-side sessions and caches these sessions in its memory heap to improve performance.

CTS supports session high availability, which lets AM manage a session as long as one of the AM servers in a clustered deployment is available. After a user has successfully authenticated, AM creates a server-side session. Any AM instance that’s configured to use the same CTS can retrieve the session and allow access to it. The user doesn’t need to sign on again unless the entire deployment goes down.

CTS provides storage for the following:

  • Server-side sessions and server-side authentication sessions

  • Session denylist (if enabled for client-side sessions)

  • Authentication session allowlist (if enabled for client-side sessions)

  • SAML 2.0-related data (if enabled for Security Token Service token validation and cancellation)

  • OAuth 2.0 and UMA 2.0 server-side tokens, and OAuth 2.0 client-side token denylist

  • Push notification data during authentication

  • Site-wide notification, such as logout or session termination notifications.

Learn more about these tokens in CTS token types.

The CTS token store is created at installation time in the external configuration store.

In general, the Core Token Service causes more volatile replication traffic due to the possibility of short-lived entries compared to regular configuration data. To handle the data volatility in high-load deployments, configure an additional DS service, separate from your configuration store, to isolate session and token information.

CTS configuration recommendations

CTS helps your deployment avoid single points of failure by providing high availability to sessions and tokens stored in its token store.

For high-volume, demanding deployments, consider the following recommendations:

  • Consider separate CTS storage for high volumes. If you require a higher-level performance threshold, you can move the CTS token storage to one or more dedicated systems rather than sharing your configuration store, as CTS generally causes much more replication traffic than less volatile configuration data. The CTS token store is the primary source for session tokens and will experience both high read and write activity depending on session usage.

  • Isolate different stores for high volumes. CTS entries are large, around 5KB, but are short-lived, whereas configuration data is static and long-lived. User entries are more dynamic than configuration data but much less volatile than CTS data.

    For high-volume deployments, consider putting CTS data in a separate DS data store and using different tuning and storage settings

  • Tune DS servers. For high performance, properly size and tune DS servers for your external CTS store.

    In addition, you can enable token compression as discussed in Manage CTS tokens. When enabled, token compression reduces load requirements on the network connection between token stores in exchange for processing time-compressing tokens.

  • Limit DS replication traffic over slow links. DS servers replicate CTS data transmitted from AM servers. For each change to a CTS token, DS replication replays the change on all DS servers in the CTS data store. The volume of replication traffic is potentially problematic over slow links.

    For high volumes when low latency is required, consider limiting the replication traffic as described in the DS documentation on standalone servers.

Deployment architectures

You can deploy CTS token stores in a number of deployment architectures, depending on your system requirements:

Affinity CTS token store

For high availability in the same data center.
Site CTS token store

For high availability across data centers.

CTS affinity deployment

With affinity load balancing for CTS, AM balances request across available DS servers, always routing LDAP requests for the same CTS token to the same directory server. This prevents AM from reading a token before DS has replicated pending changes. Affinity is well suited for deployments with many AM servers.

Configure AM’s Connection String(s) property using the AM admin UI to use server affinity without a load balancer. For more information on the Connection String(s) property, refer to External store configuration.

Learn more about CTS affinity deployments in the Knowledge Base article Best practice for using Core Token Service (CTS) Affinity based load balancing in PingAM.

The connection strings to the data or identity stores are static and not hot-swappable. This means that, if you expand or contract your DS affinity deployment, AM will not detect the change.

To work around this, either:

  • Manually add or remove the instances from the connection string and restart AM or the container where it runs.

  • Configure a DS proxy in front of the DS instances to distribute data across multiple DS shards, and configure the proxy’s URL in the connection string.

CTS site deployment

CTS supports uninterrupted session availability in deployments with multiple sites when all sites use the same globally replicated CTS store. If an entire site fails or becomes unavailable, AM servers in another site detect the failure of the site’s load balancer and attempt to use sessions from the global Core Token Service.

In the event of a failure, client applications can connect to an AM server in an active data center.

A global Core Token Service replicated across two data centers
Figure 1. Global CTS with affinity

For details on DS replication, refer to Replication in the PingDS documentation.

Configure CTS token stores

The following table summarizes the high-level tasks you must perform to configure a new instance of the CTS token store:

Task Resources

Prepare a DS server

Prepare the DS schema for CTS data.

Install and configure PingDS for CTS data

Configure AM to use the new CTS token store

Configuring a new CTS data store doesn’t migrate existing data from the old store to the new one. Usually, users will need to log in again so that AM stores their sessions and tokens in the new token store.

Configure the CTS

(Optional) Configure mTLS authentication to the CTS store

By default, AM authenticates to the CTS store using simple (username/password) authentication. To enhance security, you can configure mutual TLS (mTLS) authentication which lets AM authenticate using a trusted certificate.

Secure authentication to data stores

Test session availability

For this test, you must have a site with more than one instance. The idea is to log in a user into the first instance, shut it down, and check that the session is still available to the second instance.

Test session availability

Install and configure PingDS for CTS data

Installing DS with a setup profile creates the required backend, schema, bind user, and indexes:

  1. Follow the steps in Install DS for AM CTS in the DS documentation.

  2. Share the CTS store certificate with the AM container to prepare for TLS/LDAPS. The CTS store should communicate over secure connections for security reasons.

    DS 7 and later requires secure connections by default; therefore, share its certificate with the AM container before continuing.

    Share the DS certificate with AM

    • On the DS host, export the DS CA certificate.

      DS uses a deployment ID and password to generate a CA key pair. Learn more in Deployment IDs.

      Use the dskeymgr command to export the CA certificate:

      $ /path/to/opendj/bin/dskeymgr \
export-ca-cert \
--deploymentId $DEPLOYMENT_ID \
--deploymentIdPassword password \
--outputFile /path/to/ca-cert.pem

    • Copy the ca-cert.pem file to an accessible location on the AM host.

    • Import the DS certificate into the AM truststore:

      $ keytool \
-importcert \
-file /path/to/ca-cert.pem \
-keystore /path/to/openam/security/keystores/truststore

    Learn more about configuring AM’s truststore in Prepare the truststore.

  3. Configure the CTS store in AM.

    Refer to Configure the CTS.

    The bind DN of the service account to use when configuring the CTS store in AM is uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens.

Configure the CTS

This procedure assumes that the AM instances communicate with a single CTS instance (or load balancer), which has an FQDN of cts.example.com and is running on port 1636.

If AM cannot access the CTS token store, you will be unable to log in to the AM admin UI.

Back up your deployment before making any changes to your CTS token store configuration.

Perform the following steps to configure an external CTS token store:

  1. In the AM admin UI, go to Configure > Server Defaults, and click CTS.

  2. On the CTS Token Store tab, set the following parameters:

    CTS Token Store Parameters
    Parameter Value Notes

    Store Mode

    External Token Store

    Root Suffix

    ou=famrecords,ou=openam-session,ou=tokens

  3. On the External Store Configuration tab, configure the parameters as follows:

    External Store Configuration Parameters
    Parameter Value Notes

    SSL/TLS Enabled

    True

    When connecting to DS 7, or a DS server in production mode, enable secure connections. When you enable SSL/TLS, make sure the AM server can trust the DS server certificate and that the certificate matches the CTS store FQDN.

    Connection String(s)

    cts.example.com:1636

    Use the LDAPS port or the LDAP port with StartTLS (cts.example.com:1389).

    Login ID

    uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens

    The bind DN of the service account AM uses to connect to the directory service.

    Password

    5up35tr0ng

    Use a strong bind password for production systems.

    Heartbeat

    10

    Tune this value for production systems.

  4. Save your work.

  5. Restart AM or the web container where it runs for the changes to take effect.

Test session availability

To test session availability, use two browsers: Chrome and Firefox. You can use any two browser types, or run the browsers in incognito mode. You can also view tokens using an LDAP browser.

  1. In Chrome, log in to the second AM instance with the amAdmin user, click the realm, and click Sessions.

  2. In Firefox, log in to the first AM instance with a test user.

  3. In Chrome, verify that the test user exists in the first AM instance’s session list and not in the second instance.

  4. Shut down the first AM instance.

  5. In Firefox, rewrite the URL to point to the second AM instance.

    If successful, the browser won’t prompt for login.

  6. Confirm the session is still available.

    In Chrome, list the sessions on the second instance and observe the test user’s session.

  7. Restart the first AM instance to complete the testing.

Manage CTS tokens

You can configure AM to encrypt or compress CTS tokens as they are stored in the token store. The following properties, disabled by default, are associated with token encryption and compression:

com.sun.identity.session.repository.enableEncryption

Supports encryption of CTS tokens. Default: false.

com.sun.identity.session.repository.enableCompression

Enables GZip-based compression of CTS tokens. Default: false.

com.sun.identity.session.repository.enableAttributeCompression

Supports compression over and above the GZip-based compression of CTS tokens. Default: false.

Compression can undermine the security of encryption. You should evaluate this threat, according to your use case, before you enable compression and encryption.

Configure AM to encrypt and compress CTS tokens for storage

When encryption or compression properties are changed, all previous tokens in the LDAP store will be unreadable; thus, invalidating any user’s sessions. As a result, the user will be required to log in again.

  1. Go to Configure > Server Defaults > Advanced.

  2. Find the property you want to enable in the Property Name column.

  3. Replace the false value with true in the Property Value column.

  4. Click Save Changes.

  5. Enable the same property on every AM instance within the site.

    Failure to do so may cause unexpected issues storing and reading tokens across the environment.

  6. Restart the AM servers for the changes to take effect.

Configuring the CTS to encrypt and store tokens incurs a performance penalty for AM. If you need to encrypt the stored tokens in your environment, consider configuring the CTS token store DS instance to encrypt the data instead. For more information about encrypting a DS instance, see the Data encryption in the PingDS documentation.

CTS backups and DS replication purge delay

Replication replays each update on all directory servers, so they eventually converge on the same directory, token, session, SAML v2.0, and OAuth 2.0 data. DS data replication ensures directory services remain available for reads and writes when a server crashes or network connection goes down.

The directory servers store historical information to replay updates in the right order. DS servers periodically purge this historical information to prevent it from growing indefinitely. The setting that governs how long to retain historical information is the DS replication-purge-delay.

The default DS replication-purge-delay is 3 days. Although this setting is generally appropriate for most data, it may be too long for volatile CTS data in high-volume deployments.

If you have separated your DS servers for CTS from DS servers for other data, you can lower the replication purge delay on all DS replicas. For example, the following command sets it to 12 hours for a single DS replica on cts.example.com:

$ /path/to/opendj/bin/dsconfig \
set-synchronization-provider-prop \
--provider-name "Multimaster Synchronization" \
--set replication-purge-delay:12h \
--hostname cts.example.com \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--no-prompt

You must decide whether CTS data backups are important in your deployment. It may not be worth backing up the CTS data. Losing CTS tokens may be acceptable if the worst-case scenario means users have to log in again.

For deployments with critical long-lived sessions or long-lived refresh tokens, losing tokens may not be acceptable. If losing CTS tokens is not acceptable, back up CTS data.

When backing up CTS data, be aware that DS backups older than the replication purge delay are useless. DS replication can only bring a replica up to date when it has the historical information to replay changes in the right order. If you restore a DS server from data older than the replication purge delay, the other DS servers will have already purged the historical information needed to replay the pending changes. For details, refer to Backup and restore in the PingDS documentation.

Manage expired CTS tokens

Tokens in the CTS store have a limited time to live, after which they expire and must be pruned. By default, AM manages expired tokens by using its own reaper. You can, however, delegate this task to DS.

Although both solutions work equally well, using DS to manage token expiration instead of AM’s reaper frees up resources in AM servers that can then be used for policy or authorization requests.

The following topics explain the two methods of managing expired CTS tokens in detail.

Manage expired tokens with the AM CTS reaper

When an AM server modifies a token in the CTS token store, it takes responsibility for managing that token when it expires. Each AM server maintains a local cache of expired tokens to delete, and when to delete them.

Using the local reaper cache reduces the number of searches to the CTS store to determine expired tokens to delete. This improves overall cluster performance. Servers still search the CTS store for expired tokens occasionally, to ensure expired tokens aren’t missed when a server in the cluster goes down.

The AM CTS reaper is enabled by default and requires no extra configuration. If you’ve configured the DS expiration and deletion feature instead, and then want to re-enable the AM CTS reaper, read Re-enable the AM reaper.

Manage expired tokens using DS

If you disable the AM CTS reaper, AM relies on DS capabilities to delete expired tokens.

DS doesn’t reap its contents by default–you must configure DS to expire and delete entries. Entry expiration and deletion uses an ordering index to find CTS tokens that have reached their time to live then expire and delete them.

Before you configure DS to manage CTS token expiration, consider the following points:

  • DS doesn’t replicate entry deletion across servers. You must make sure all CTS store replicas are configured in the same way. For details, refer to Entry expiration in the DS documentation.

  • Disabling the AM reaper impacts session-related functionality, such as sending notifications about session expiration or timeouts to agents.

    When you completely disable the AM reaper, the following session functionality becomes unavailable:

    • Implementations of org.forgerock.openam.cts.reaper.TokenDeletionStrategy, responsible for deleting expiring tokens.

      Custom logic for specific token types (unrelated to simply deleting tokens) no longer works.

    • Implementations of org.forgerock.openam.cts.continuous.watching.ContinuousListener and org.forgerock.openam.cts.continuous.watching.ContinuousWatcher no longer receive deletion notifications in case of session timeout.

      Active logout is not impacted.

    • Code built on top of com.iplanet.dpro.session.service.SessionEventListener no longer receives IDLE_TIMEOUT or MAX_TIMEOUT events. This affects:

      • Session timeout monitoring

      • Session timeout auditing

      • Session timeout logging

      • Session timeout notifications for agents (PLL, WebSockets)

      • Timeout handlers configured through the openam-session-timeout-handler-list

      • Session web hooks registered during authentication

    • Code built on top of com.iplanet.dpro.session.watchers.listeners.SessionDeletionListener no longer receives notifications when the session idle or maximum lifetime is exceeded (common usage includes caches).

    • Listeners built on top of com.sun.identity.plugin.session.SessionListener no longer receive notifications on active logout or when the maximum session time is reached (idle timeout is ignored).

    If you don’t need these session capabilities, refer to Let DS manage CTS tokens (ignore session capabilities).

    If you do need these session capabilities, refer to Let DS manage CTS tokens (retain session capabilities).

A common CTS token management strategy is to configure AM to reap session tokens only, and to use DS to manage non-session tokens. This configuration lets you retain session-related functionality, while benefiting from DS’s token management capabilities.

If your environment requires it, you can also configure the AM reaper to manage different subsets of tokens other than session tokens.

Let DS manage CTS tokens (ignore session capabilities)

These steps assume you don’t need the session capabilities impacted by disabling the AM CTS reaper. They configure DS to manage expiration and deletion of all CTS tokens in your environment.

  1. Perform one of the following steps, depending on whether you’re installing a new DS instance for CTS, or modifying an existing instance:

    • If you’re installing a new DS instance, use the CTS setup profile.

      Choose the option "DS manages all token expiration".

    • If you have an existing DS instance that you’re using as a CTS store, configure the DS entry expiration and deletion feature for the coreTokenExpirationDate attribute.

      This attribute is already indexed, but you must enable the TTL-related properties: 
      $ /path/to/opendj/bin/dsconfig set-backend-index-prop \
--hostname 'ds.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backend-name amCts \
--index-name coreTokenExpirationDate \
--set ttl-enabled:true \
--set ttl-age:10s \
--no-prompt

      DS doesn’t replicate entry deletion across servers. You must configure all CTS store replicas in the same way. Learn more in Entry expiration in the DS documentation.

  2. Disable the AM CTS reaper.

    Go to Configure > Server Defaults > Advanced and set the org.forgerock.services.cts.store.reaper.enabled property to false.

    This change doesn’t require a server restart. Learn more about this advanced server property in Advanced properties.

    Perform this step on all AM servers in your deployment.

Let DS manage CTS tokens (retain session capabilities)

These steps assume you need the session capabilities that would be impacted by disabling the AM CTS reaper. They configure AM to reap SESSION tokens, while using DS capabilities to manage other tokens.

  1. Perform one of the following steps, depending on whether you’re installing a new DS instance for CTS, or modifying an existing instance:

    • If you’re installing a new DS instance, use the CTS setup profile.

      Choose the option "AM reaper manages only SESSION token expiration".

    • If you’re modifying an existing DS instance, follow these steps:

      1. Copy the value of the coreTokenExpirationDate attribute to the coreTokenTtlDate for all existing tokens except for SESSION tokens.

        AM will manage the SESSION tokens separately.

        If you don’t perform this step, neither the AM reaper nor the DS expiration feature will delete these tokens. They’ll remain in the CTS store until you remove them manually.

      2. Create an ordering index for the coreTokenTtlDate attribute:

        $ /path/to/opendj/bin/dsconfig create-backend-index \
--hostname 'ds.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backend-name amCts \
--index-name coreTokenTtlDate \
--set index-type:ordering \
--no-prompt

      3. Rebuild the new index using the rebuild-index command:

        $ /path/to/opendj/bin/rebuild-index \
--hostname 'ds.example.com' \
--clearDegradedState \
--port 4444 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--baseDN "dc=cts,dc=example,dc=com" \
--index coreTokenTtlDate

      4. Configure entry expiration and deletion for the coreTokenTtlDate index you created in the previous step:

        $ /path/to/opendj/bin/dsconfig set-backend-index-prop \
--hostname 'ds.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--index-name coreTokenTtlDate \
--backend-name amCts \
--set ttl-enabled:true \
--set ttl-age:10s \
--no-prompt
      DS doesn’t replicate deletion of entries across servers. You must configure all CTS store replicas in the same way.

      For more information, refer to Entry expiration in the DS documentation.

  2. In the AM admin UI, go to Configure > Server Defaults > Advanced and configure the following advanced server properties for each AM server that shares the CTS store cluster:

    • Set org.forgerock.services.cts.store.ttlsupport.enabled to true.

    • Set org.forgerock.services.cts.store.ttlsupport.exclusionlist to SESSION.

    • Set org.forgerock.services.cts.store.reaper.enabled to true.

    The changes are effective immediately. Learn more about these advanced server properties in Advanced properties.

Re-enable the AM reaper

Follow these steps if you previously enabled the DS expiration and deletion feature but want to disable it and re-enable the AM reaper.

  1. If you enabled the DS expiration and deletion feature following the steps in Let DS manage CTS tokens (ignore session capabilities), follow these steps to enable the AM CTS reaper for all tokens:

    • Disable DS entry expiration and deletion for the coreTokenExpirationDate index:

      $ /path/to/opendj/bin/dsconfig set-backend-index-prop \
--hostname 'ds.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backend-name amCts \
--index-name coreTokenExpirationDate \
--set ttl-enabled:false \
--no-prompt
      Don’t delete the index. Configure all CTS store replicas in the same way.

    • Re-enable the AM CTS reaper:

      On each AM server in your deployment, go to Configure > Server Defaults > Advanced and set the org.forgerock.services.cts.store.reaper.enabled property to true.

  2. If you enabled the DS expiration and deletion feature following the steps in Let DS manage CTS tokens (retain session capabilities), follow these steps to enable the AM CTS reaper for all tokens:

    • Disable the DS entry expiration and deletion feature for the coreTokenTtlDate index. For example:

      $ /path/to/opendj/bin/dsconfig set-backend-index-prop \
--hostname 'ds.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--index-name coreTokenTtlDate \
--backend-name amCts \
--set ttl-enabled:false
      Configure all CTS store replicas in the same way.

    • Delete the index created for the coreTokenTtlDate attribute. For example:

      $ /path/to/opendj/bin/dsconfig delete-backend-index \
--hostname 'ds.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--truststorepassword:file /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backend-name amCts \
--index-name coreTokenTtlDate \
--no-prompt
      Configure all CTS store replicas in the same way.

    • Go to Configure > Server Defaults > Advanced and configure the following advanced server properties in all of the AM servers sharing the CTS store cluster:

      • Set org.forgerock.services.cts.store.ttlsupport.enabled to false.

      • Remove the org.forgerock.services.cts.store.ttlsupport.exclusionlist property from the configuration.

      • Set org.forgerock.services.cts.store.reaper.enabled to true.

    The changes are effective immediately. For more information about these advanced server properties, see Advanced properties.

Tune the CTS

There are several tuning considerations for the efficient processing of your CTS token store:

Task Resources

Configure the reaper cache size

The reaper process prunes tokens in the store that have reached their maximum time-to-live.

Reaper cache size

Manage the reaper search size

In addition to the cache, the reaper also uses a search to find expired tokens. You can tune the maximum amount of tokens that the reaper can find and delete in a single invocation.

Reaper search size

Change the OAuth 2.0 Storage Scheme

If the CTS token store was created on a version of AM earlier than 6.5, configure the grant-set scheme to improve the performance of OAuth 2.0-related operations.

OAuth 2.0 CTS storage scheme

Set the poll interval for the logout user cache

In a multi-server deployment, servers poll the CTS at a specified interval to update their logout user token cache with the tokens from other servers.

CTS poll interval

Reaper cache size

The size of the AM reaper cache is controlled by the org.forgerock.services.cts.reaper.cache.size advanced property. The default size is 500000 tokens.

If an AM server is under sustained heavy load, the reaper cache may reach capacity, causing degraded performance due to the additional slower searches of the CTS store. If the reaper cache is full, messages are logged in the Session debug log, such as the following:

The CTS token reaper cache is full. This will result in degraded performance.
You should increase the cache size by setting the advanced server property
'org.forgerock.services.cts.reaper.cache.size' to a number higher than 500000.

If this debug message appears frequently in the debug logs, increase the value of the org.forgerock.services.cts.reaper.cache.size property. To alter the value, in the AM admin UI, go to Configure > Server Defaults > Advanced, and add the property and increased value to the list.

Increasing the size of the reaper cache causes higher memory usage on the AM server. If a cache of the default size of 500000 entries is nearly full, the server memory used could be up to approximately 100 megabytes.

Tune the AM reaper cache size only if the org.forgerock.services.cts.store.reaper.enabled advanced server property is set to true.

Reaper search size

The reaper uses its cache to ensure that expired tokens are removed from the CTS token store, but it also has a built-in mechanism to search for expired tokens that may have not been purged. This could happen, for example, due to an AM instance crash.

When the reaper searches for expired tokens, DS returns a page of records, and the reaper deletes these tokens.

To configure the maximum number of records that DS returns, use the org.forgerock.services.cts.reaper.search.tokenLimit advanced server property. The default is 5000.

To configure how often the search runs, and the grace period for the tokens the reaper deletes, configure the following properties:

  • org.forgerock.services.cts.reaper.search.pollFrequencyMilliseconds.

    Specifies how often to perform a search for expired tokens. The default is 5000 milliseconds.

    The value of this setting should never be higher than a few seconds, as the goal is to launch the search frequently so that the expired tokens do not pile up.

  • org.forgerock.services.cts.reaper.search.gracePeriodMilliseconds.

    Specifies the grace period used when searching for expired tokens. Any tokens that expired more than the specified duration ago are returned. The default is 300000 milliseconds.

    Set the grace period larger than the value controlled by the org.forgerock.services.cts.reaper.cache.pollFrequencyMilliseconds advanced property. This allows an AM instance sufficient time to delete the token using its cache, rather than search.

    Deleting from the cache is preferred because it avoids expensive searches against the CTS store.

To tune the reaper searches, run load tests in your environment with the default reaper parameters, and then watch if the expired tokens build up. If there is no token build-up, then the reaper is sufficiently tuned. If you see token build-up, tune the reaper cache first, as it is the less expensive of the two reaping mechanisms.

It is fine if there is a small amount of expired tokens left on each iteration of the reaper search as long as tokens are cleared up during lower activity periods.

Keeping a large number of expired tokens in the CTS store results in increased disk space usage, and in AM not sending expiration notifications in a timely fashion.

Setting the token limit too high could negatively affect the performance of the DS instance. It is better to launch more runs of the reaper search with smaller amounts of records, than fewer runs with larger amounts of records.

OAuth 2.0 CTS storage scheme

AM 6.5 introduced a new scheme for storing OAuth 2.0 tokens in the CTS store, called the grant-set scheme.

The grant-set scheme groups multiple authorizations for a given OAuth 2.0 client and resource owner pair and stores them in a single CTS OAUTH2_GRANT_SET entry. This implementation reduces the size and quantity of entries stored, as well as the number of calls required to perform OAuth 2.0 operations.

The one-to-one scheme stores the state of multiple authorizations for a given OAuth 2.0 client and resource owner pair across multiple OAUTH and OAUTH2_STATELESS_GRANT entries and is more resource intensive. You should upgrade to the grant-set scheme after all the servers in your environment have been upgraded to AM 6.5 or later.

The grant-set scheme is backwards-compatible with existing entries stored in the CTS store. Therefore, any access or refresh token issued before configuring the grant-set scheme is still valid. The CTS store retains an existing token in its original form until the refresh token expires or the token is actively revoked.

Users do not notice any change in the tokens they receive. There is no change to the OAuth 2.0 endpoints.

Learn more about these tokens in CTS token types.

To enable the grant-set scheme:

  1. Go to Configure > Global Services > OAuth2 Provider > Global Attributes.

  2. In the CTS Storage Scheme drop-down, choose Grant-Set Storage Scheme.

  3. Click Save Changes.

New OAuth 2.0 tokens stored in the CTS after the change use the new scheme automatically.

CTS poll interval

If client-side session logout is enabled, AM stores the logout user tokens in a local cache. In a multi-server deployment, servers poll the CTS at a specified interval to update their logout user token cache with the tokens from other servers.

The poll interval is specified by the global session property Enable Invalidation of Sessions Based on User Identifier, and is set to 60 seconds by default.

A very long polling interval gives malicious users time to connect to other AM servers within a site and use stolen session cookies. A very short polling interval improves security by invalidating user sessions across servers in a shorter timeframe, but can incur a performance cost.

A value of 0 disables polling of the CTS. Do not disable polling in a multi-server site, as this prevents logoutByUser session invalidation data from being shared between servers.