--- title: Manage expired CTS tokens description: 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. component: pingam version: 8.1 page_id: pingam:cts:cts-reaper canonical_url: https://docs.pingidentity.com/pingam/8.1/cts/cts-reaper.html keywords: ["CTS Store (Sessions & Tokens)", "Setup & Configuration", "Directory Server"] page_aliases: ["cts-guide:cts-reaper.adoc"] section_ids: manage_expired_tokens_with_the_am_cts_reaper: Manage expired tokens with the AM CTS reaper manage_expired_tokens_using_ds: Manage expired tokens using DS cts-ds-reaper-all-tokens: Let DS manage CTS tokens (ignore session capabilities) cts-ds-reaper-no-sessions: Let DS manage CTS tokens (retain session capabilities) cts-am-reaper: Re-enable the AM reaper --- # 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](#cts-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](https://docs.pingidentity.com/pingds/8.1/config-guide/import-export.html#backend-ttl) 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)](#cts-ds-reaper-all-tokens). If you do need these session capabilities, refer to [Let DS manage CTS tokens (retain session capabilities)](#cts-ds-reaper-no-sessions). | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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](https://docs.pingidentity.com/pingds/8.1/install-guide/profile-am-cts.html). 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: | ```bash $ /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](https://docs.pingidentity.com/pingds/8.1/config-guide/import-export.html#backend-ttl) 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](../setup/server-advanced.html). 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](https://docs.pingidentity.com/pingds/8.1/install-guide/profile-am-cts.html). 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: ```bash $ /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: ```bash $ /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 ``` 4. Configure entry expiration and deletion for the `coreTokenTtlDate` index you created in the previous step: ```bash $ /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](https://docs.pingidentity.com/pingds/8.1/config-guide/import-export.html#backend-ttl) 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](../setup/server-advanced.html). ## 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)](#cts-ds-reaper-all-tokens), follow these steps to enable the AM CTS reaper for all tokens: * Disable DS entry expiration and deletion for the `coreTokenExpirationDate` index: ```bash $ /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)](#cts-ds-reaper-no-sessions), 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: ```bash $ /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: ```bash $ /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](../setup/server-advanced.html).