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.

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

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:

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.

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

Rebuild the new index using the rebuild-index command:

$ /path/to/opendj/bin/rebuild-index \
--hostname 'ds.example.com' \
--clearDegradedState \
--port 4444 \
--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

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.

Learn more in Entry expiration in the DS documentation.

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.

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