FAQ
ForgeRock Identity Platform
Does not apply to Identity Cloud

FAQ: Core Token Service (CTS) and session high availability in AM

Last updated Jun 2, 2021

The purpose of this FAQ is to provide answers to commonly asked questions regarding CTS and session high availability in AM. Session high availability was formerly referred to as session failover.


2 readers recommend this article

Frequently asked questions

Q. Can I use any LDAP server for the CTS store?

A. No, DS is the only supported backend for the CTS store. See Core Token Service Guide (CTS) (AM 7 and later) or Best practice for configuring an external DS instance for the Core Token Service (CTS) in AM 5.x and 6  for further information.

Q. Can I use the embedded CTS store in production?

A. We recommend that you use an external CTS store in production as it allows you to tune the LDAP server containing the CTS store separately to the LDAP server containing the configuration store. Typically, a directory containing tokens that change frequently and are relatively large (CTS store) needs different tuning to a directory containing data that is relatively stable (configuration store). Being able to tune these stores separately gives you greater control over performance. This is discussed in more detail in Core Token Service Guide (CTS) › General Recommendations for CTS Configuration.

Additionally, you cannot use the embedded DS in production for anything in AM 7 and later.

However, in pre-AM 7 if you have a small scale deployment that is relatively simple, the embedded CTS store may be suitable for your needs; you should performance test this option to check it is appropriate to use the embedded CTS store.

Q. What's the best way of shutting down a CTS server?

A. When shutting down a CTS server, it is good practice to disable the AM facing connection handler (LDAPS, HTTP etc) to minimize the impact of replication delay, especially in a busy affinity enabled topology. Disabling the connection handler instantly closes the connections to AM, but keeps replication flowing, which allows the replica to propagate changes before being shutdown. 

These example steps disable the LDAP/LDAPS connection handler that AM is configured to communicate on to stop updates reaching the CTS instance. You must use an alternative LDAP connector for subsequent LDAP operations. If this is not possible, consider temporarily changing the port or blocking communications at the network level instead.

  1. Disable the LDAP/LDAPS connector so that AM stops sending traffic to this node providing you have an alternative LDAP connector for subsequent LDAP operations. For example, to disable the LDAP connection handler:
    • DS 7.1 and later: $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN uid=admin --bindPassword password --handler-name LDAP --set enabled:false --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
    • DS 7: $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN uid=admin --bindPassword password --handler-name LDAP --set enabled:false --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
    • Pre-DS 7: $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name LDAP --set enabled:false --trustAll --no-prompt
  2. Stop DS.
  3. Start DS.
  4. Re-enable the LDAP/LDAPS connector to resume AM sending traffic to this node. For example, to enable the LDAP connection handler:
    • DS 7.1 and later: $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN uid=admin --bindPassword password --handler-name LDAP --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePassword:file /path/to/ds/config/keystore.pin --no-prompt
    • DS 7: $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN uid=admin --bindPassword password --handler-name LDAP --set enabled:true --usePkcs12TrustStore /path/to/ds/config/keystore --trustStorePasswordFile /path/to/ds/config/keystore.pin --no-prompt
    • Pre-DS 7: $ ./dsconfig set-connection-handler-prop --hostname host1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password --handler-name LDAP --set enabled:true --trustAll --no-prompt

Q. How can I clear the CTS queue?

A. Normally you don't need to clear the CTS queue as it's preferable to manage it by tuning the size and timeout appropriately as detailed in: Core Token Service Guide (CTS) › Queue Size and Timeout.

However, if the queue has become overwhelmed, for example, due to a brute force attack, you can clear the queue by restarting AM. 

Q. Is the CTS store only used for session tokens?

A. No, the CTS store is used for a variety of tokens, such as OAuth, SAML and REST.

See Understanding CTS token types in AM for further information.

Q. Is it normal for a session token to be a negative number?

A. Yes it is normal due to the way in which session tokens (or coreTokenId attributes) are generated; it does not indicate an error. Session tokens are generated as follows:

  • They are composed of: <storage key (generated using SecureRandom)> + <legacy sessionID extension>
  • This value is then encrypted to a string.
  • This string is then converted to a String object using Hex.decodeHex() when the session token is generated. This step can sometimes produce a negative number.

Example

You may see session tokens with negative numbers, for example:

CTS: Create: Created SESSION Token -662229285778566861

Or see them represented as a coreTokenId attribute in your LDAP browser, for example:

Attribute Description Value --------------------- ----- coreTokenId -662229285778566861

Q. Can I use a load balancer with my CTS deployment?

A. You should avoid using a load balancer in front of the CTS stores as detailed in Core Token Service Guide (CTS) › General Recommendations for CTS Configuration.

See Best practice for configuring an external DS instance for the Core Token Service (CTS) in AM 5.x and 6for further information.

Q. Can I improve CTS performance?

A. Yes, you can tune the DS server to improve CTS performance as discussed in FAQ: DS performance and tuning.

All requests are made asynchronously in the background, which increases performance as CPU and memory are better utilized. There are also two properties available (queue size and queue timeout) which can be set to tune CTS further as detailed in Core Token Service Guide (CTS) › Tuning the CTS.

Q. Can I configure the external CTS token store using ssoadm?

A. Yes you can provided the external CTS token store already exists (and you just want to modify its configuration using ssoadm) or you have taken steps to prepare the external DS instance for CTS first. See How do I configure an external CTS token store in AM (All versions) using Amster or ssoadm? for further information.

Q. Are sessions replicated across AM servers?

A. No, sessions are not replicated across AM servers; the CTS tokens that represent the user's session are replicated to all DS nodes for which you have configured replication.

This is discussed in more detail in Core Token Service Guide (CTS) › CTS Backups and DS Replication Purge Delay.

Q. Can I disable replication-purge-delay for the CTS backend?

A. No, the replication-purge-delay property cannot be set for an individual backend.

See Also

Best practice for configuring an external DS instance for the Core Token Service (CTS) in AM 5.x and 6

Best practice for using Core Token Service (CTS) Affinity based load balancing in AM (All versions)

How do I configure an external CTS token store in AM (All versions) using Amster or ssoadm?

Core Token Service (CTS) and sessions in AM

Core Token Service Guide (CTS)

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.