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

Prerequisites

The external CTS token store must already exist (and you just want to modify its configuration) or you must take steps to prepare the external DS instance for CTS first if you want to automate the entire process.

See Core Token Service Guide (CTS) › Configuring CTS Token Stores (AM 6.5 and later) or Best practice for configuring an external DS instance for the Core Token Service (CTS) in AM 5.x and 6 for the steps needed to configure an external DS instance for CTS. In summary, these steps are:

1. Prepare the DS Server. In pre-AM 6.5, this step is split into 3 sub-steps as follows:
   1. DS base build and CTS data (container and schema) import.
   2. Non-admin user creation and ACI import.
   3. CTS index import and rebuild.
2. AM console configuration.
3. Testing session failover.

You must complete step 1 prior to configuring an external CTS token store in AM. You can then use these instructions to complete step 2 using Amster or ssoadm instead of using the console if you wish.

Configuring an external CTS token store (Amster)

You can configure an external CTS token store using Amster as follows:​

1. Take a backup of your configuration data as described in Maintenance Guide › Backing Up Configurations (AM 7 and later) or How do I make a backup of configuration data in AM 5.x or 6.x?
2. Connect to AM using Amster, for example: $ ./amster am> connect --interactive http://host1.example.com:8080/openam Sign in to top level realm User Name: amadmin Password: **********
3. Run the read command against the DefaultCtsDataStoreProperties entity to get the current configuration, for example (exclude the --prettyPrint option in Amster 5.x): am> read DefaultCtsDataStoreProperties --global --prettyPrint falseExample response: ===> {"amconfig.org.forgerock.services.cts.store.common.section":{"org.forgerock.services.cts.store.location":"default","org.forgerock.services.cts.store.root.suffix":"","org.forgerock.services.cts.store.max.connections":"10","org.forgerock.services.cts.store.page.size":"0","org.forgerock.services.cts.store.vlv.page.size":"1000"},"amconfig.org.forgerock.services.cts.store.external.section":{"org.forgerock.services.cts.store.password":null,"org.forgerock.services.cts.store.loginid":"","org.forgerock.services.cts.store.heartbeat":"10","org.forgerock.services.cts.store.ssl.enabled":"","org.forgerock.services.cts.store.directory.name":""},"_rev":"758717280","_id":"null/properties/cts"}
4. Copy the outputted JSON response and make the following changes:
   • Update the necessary property values to point to the external CTS store: you must set org.forgerock.services.cts.store.location to external, org.forgerock.services.cts.store.root.suffix to a relevant suffix and specify values for the properties in the amconfig.org.forgerock.services.cts.store.external.section. See Entity Reference › CtsDataStoreProperties: update for further information.
   • Remove the end of the response starting with ,"_rev" (leaving the closing curly bracket). The string to remove includes the _id field and possibly others such as _type. You would remove the following from the end of the response in this example: ,"_rev":"758717280","_id":"null/properties/cts"
   • Amster 5.5 only: Remove the line breaks (for example, using sed or an online tool).
5. Run the update command against the DefaultCtsDataStoreProperties entity, passing the edited JSON response in the body. You must enclose the JSON response in single quotes. For example: am> update DefaultCtsDataStoreProperties --global --body '{"amconfig.org.forgerock.services.cts.store.common.section":{"org.forgerock.services.cts.store.location":"external","org.forgerock.services.cts.store.root.suffix":"ou=tokens","org.forgerock.services.cts.store.max.connections":"10","org.forgerock.services.cts.store.page.size":"0","org.forgerock.services.cts.store.vlv.page.size":"1000"},"amconfig.org.forgerock.services.cts.store.external.section":{"org.forgerock.services.cts.store.password":"password1","org.forgerock.services.cts.store.loginid":"uid=openam_cts,ou=admins,ou=famrecords,ou=openam-session,ou=tokens","org.forgerock.services.cts.store.heartbeat":"10","org.forgerock.services.cts.store.ssl.enabled":"","org.forgerock.services.cts.store.directory.name":"ds1.example.com:389,ds2.example.com:50389"}}'
6. Restart the web application container in which AM runs.

Configuring an external CTS token store (ssoadm)

You can configure an external CTS token store using ssoadm as follows:​

1. Take a backup of your configuration data as described in Maintenance Guide › Backing Up Configurations (AM 7 and later) or How do I make a backup of configuration data in AM 5.x or 6.x?
2. Create a data file (called DATA_FILE to match the next command) and include the following properties with appropriate values (example values are shown):  ​org.forgerock.services.cts.store.directory.name=ds1.example.com:389,ds2.example.com:50389 org.forgerock.services.cts.store.heartbeat=10 org.forgerock.services.cts.store.location=external org.forgerock.services.cts.store.loginid=uid=user org.forgerock.services.cts.store.max.connections=10 org.forgerock.services.cts.store.password=password org.forgerock.services.cts.store.root.suffix=dc=example,dc=com org.forgerock.services.cts.store.ssl.enabled=false
3. Enter the following command: $ ./ssoadm update-server-cfg -s [serverName] -u [adminID] -f [passwordfile] -D DATA_FILEreplacing [serverName], [adminID] and [passwordfile] with appropriate values. You can use default for [serverName] if you want to change the Default Server Settings.
4. Restart the web application container in which AM runs.

If you only want to update some of the configuration settings, you can specify just the attributes you want to change. For example, to change the maximum number of connections, you could use the following ssoadm command:

• AM 7 and later: $ ./ssoadm update-server-cfg -s default -u uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org -f pwd.txt -a org.forgerock.services.cts.store.max.connections=17
• Pre-AM 7: $ ./ssoadm update-server-cfg -s default -u amadmin -f pwd.txt -a org.forgerock.services.cts.store.max.connections=17

See Also

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

Login to AM console (All versions) fails for amAdmin user

FAQ: Installing and using ssoadm in AM

Core Token Service Guide (CTS)

Core Token Service Guide (CTS) › Tuning the CTS

Related Training

N/A

Related Issue Tracker IDs

N/A