Configuring the CTS Reaper

Tokens in the CTS store have a time to live after which they must be pruned. AM can manage expired tokens by either using its own reaper (the default) or by delegating the task to DS. Both AM and DS are equally adept at managing expired tokens. However, choosing DS to manage token expiration in the place of AM's reaper frees resources in the AM servers than can then be used for policy or authorization requests.

Review the following list for more information about the different configurations:

AM CTS Reaper (Default)

When an AM server modifies a token in the CTS token store, it also takes responsibility to manage it when it expires. To determine which tokens have expired, each AM server maintains a local cache of which tokens to delete and when. This reduces the number of relatively slow queries to the CTS store.

Use of the local reaper cache means fewer searches to the CTS store to determine expired tokens to delete, which improves overall cluster performance. A search of the CTS store for expired tokens is still performed as a fail safe, to ensure expired tokens are not missed when a server in the cluster goes down.

The AM CTS reaper is enabled by default. However, if you have configured the DS expiration and deletion feature, and you need to enable the AM CTS reaper again, see "To Enable the AM Reaper".

DS Entry Expiration and Deletion Feature

When the AM CTS reaper is disabled, AM relies on DS capabilities to delete expired tokens.

By default, DS does not reap its contents, so you need to configure the entry expiration and deletion feature manually. This feature uses an ordering index to find those tokens that have reached their time to live and expires (deletes) them.

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

The CTS token store must be in DS version 6.0 or later.
Deletion of entries is not replicated across DS servers. Therefore, you must ensure all the CTS store replicas are configured in the same way. For more information, see Automating Entry Expiration and Deletion in the ForgeRock Directory Services Maintenance Guide.
Completely disabling the AM reaper impacts session-related functionality, such as sending notifications about session expiration or timeouts to agents.
Tip
A common implementation to manage CTS tokens is to configure AM to reap session tokens only, while using DS capabilities to manage the non-session tokens. This configuration ensures your environment still can make use of all session functionality, while benefiting from DS's capabilities as well.
You can configure the AM reaper to manage different subsets of tokens other than session tokens, too, if your environment requires it.
The following is a list of session functionality that is not available when the AM reaper is completely disabled:
- Implementations of org.forgerock.openam.cts.reaper.TokenDeletionStrategy, which are responsible for deleting expiring tokens. Any custom logic for specific token types that is not related to simply deleting tokens no longer work.
- 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 via 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, nor when the maximum session time is reached (idle timeout is ignored).
If your environment does not require the session capabilities listed above, see "To Enable DS to Manage the Tokens in the CTS Store (Impacted Session Capabilities Not Required) ".
If your environment requires the session capabilities above, see "To Enable DS to Manage the Tokens in the CTS Store (Impacted Session Capabilities Required)".

To Enable DS to Manage the Tokens in the CTS Store (Impacted Session Capabilities Not Required)

This procedure assumes you have ensured that your environment does not require the session capabilities impacted by stopping the AM CTS reaper. Perform the steps in this procedure to configure DS to manage expiration and deletion of all CTS tokens in your environment:

Perform one of the following options depending on whether you are installing a new Directory Services instance for CTS, or are modifying an existing instance:
- If you are creating a new instance of Directory Services for use with CTS, perform the following step:
  1. Use a setup profile, and set the tokenExpirationPolicy property to ds.
    For more information, see DS for AM CTS in the Directory Services Installation Guide.
- If you are modifying an existing instance of Directory Services for use with CTS, perform the following step:
  1. Configure the DS entry expiration and deletion feature for the coreTokenExpirationDate attribute. Note that the attribute is already indexed, but requires the TTL-related properties to be enabled. For example:
```
$ /path/to/opendj/bin/dsconfig set-backend-index-prop \
--hostname 'cts.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backend-name ctsStore \
--index-name coreTokenExpirationDate \
--set ttl-enabled:true \
--set ttl-age:10s \
--no-prompt
```
    Deletion of entries is not replicated across DS servers. Therefore, you must ensure all the CTS store replicas are configured in the same way. For more information, see Entry Expiration in the ForgeRock Directory Services Maintenance Guide.
Disable the AM CTS reaper by navigating to Configure > Server Defaults > Advanced and setting the org.forgerock.services.cts.store.reaper.enabled property to false on all the AM servers on your deployment.
The changes are effective immediately.
For more information about these advanced server properties, see "Advanced Properties".

To Enable DS to Manage the Tokens in the CTS Store (Impacted Session Capabilities Required)

This procedure assumes that your environment requires the session capabilities that would be impacted by stopping the AM CTS reaper. Perform the steps in this procedure to configure AM to reap SESSION tokens only, while using DS capabilities to manage the rest:

Perform one of the following options depending on whether you are installing a new Directory Services instance for CTS, or are modifying an existing instance:
- If you are creating a new instance of Directory Services for use with CTS, perform the following step:
  1. Use a setup profile, and set the tokenExpirationPolicy property to am-sessions-only.
    For more information, see DS for AM CTS in the Directory Services Installation Guide
- If you are modifying an existing instance of Directory Services for use with CTS, perform the following steps:
  1. (Optional) If you have existing tokens in the CTS store, you must copy the value of the coreTokenExpirationDate attribute to the coreTokenTtlDate for all the existing tokens except for SESSION tokens.
    AM will manage the SESSION tokens separately.
    If you do not perform this step, neither the AM reaper nor the DS expiration feature will delete these tokens and they will remain untouched in the CTS store until manually removed.
  2. Create an ordering index for the coreTokenTtlDate attribute. For example:
```
$ /path/to/opendj/bin/dsconfig create-backend-index \
--hostname 'cts.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backend-name ctsStore \
--index-name coreTokenTtlDate \
--set index-type:ordering \
--no-prompt
```
    Deletion of entries is not replicated across DS servers. Therefore, you must ensure all the CTS store replicas are configured in the same way.
  3. Rebuild the new index using the rebuild-index command. For example:
```
$ /path/to/opendj/bin/rebuild-index \
--hostname 'cts.example.com' \
--port 4444 \
--useSsl \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--baseDN "dc=cts,dc=example,dc=com" \
--index coreTokenTtlDate
```
    Deletion of entries is not replicated across DS servers. Therefore, you must ensure all the CTS store replicas are configured in the same way.
  4. Configure DS's entry expiration and deletion feature in the CTS store for the coreTokenTtlDate index created in the previous steps. For example:
```
$ /path/to/opendj/bin/dsconfig set-backend-index-prop \
--hostname 'cts.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--index-name coreTokenTtlDate \
--backend-name ctsStore \
--set ttl-enabled:true \
--set ttl-age:10s \
--no-prompt
```
    Deletion of entries is not replicated across DS servers. Therefore, you must ensure all the CTS store replicas are configured in the same way.
    For more information, see Entry Expiration in the ForgeRock Directory Services Maintenance Guide.
In the AM administration console, navigate 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 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.
For more information about these advanced server properties, see "Advanced Properties".

To Enable the AM Reaper

This procedure assumes you enabled the DS expiration and deletion feature and you want to disable it and enable the AM reaper again:

(Optional) If you enabled the DS expiration and deletion feature, following the steps in "To Enable DS to Manage the Tokens in the CTS Store (Impacted Session Capabilities Not Required) ", perform the following steps to enable the AM CTS reaper for all tokens:
1. Disable the DS entry expiration and deletion feature for the coreTokenExpirationDate index. Note that you should not delete the index. For example:
```
$ /path/to/opendj/bin/dsconfig set-backend-index-prop \
--hostname 'cts.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backend-name ctsStore \
--index-name coreTokenExpirationDate \
--set ttl-enabled:true \
--set ttl-age:10s \
--no-prompt
```
  Ensure that all the CTS store replicas are configured in the same way.
2. Enable the AM CTS reaper by by navigating to Configure > Server Defaults > Advanced and setting the org.forgerock.services.cts.store.reaper.enabled property to true on all the AM servers on your deployment.
(Optional) If you enabled the DS expiration and deletion feature following the steps in "To Enable DS to Manage the Tokens in the CTS Store (Impacted Session Capabilities Required)", perform the following steps to enable the AM CTS reaper for all tokens:
1. Disable the DS entry expiration and deletion feature for the coreTokenTtlDate index. For example:
```
$ /path/to/opendj/bin/dsconfig set-backend-index-prop \
--hostname 'cts.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--index-name coreTokenTtlDate \
--backend-name ctsStore \
--set ttl-enabled:false
```
  Ensure that all the CTS store replicas are configured in the same way.
2. Delete the index created for the coreTokenTtlDate attribute. For example:
```
$ /path/to/opendj/bin/dsconfig delete-backend-index \
--hostname 'cts.example.com' \
--port 4444 \
--usePkcs12TrustStore /path/to/opendj/config/keystore \
--trustStorePasswordFile /path/to/opendj/config/keystore.pin \
--bindDN uid=admin \
--bindPassword str0ngAdm1nPa55word \
--backend-name ctsStore \
--index-name coreTokenTtlDate \
--no-prompt
```
  Ensure that all the CTS store replicas are configured in the same way.
3. Navigate 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".

Configuring the CTS Reaper

Tip