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 Configure 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 6.0.x for the steps needed to configure an external DS instance for CTS. In summary, these steps are:

1. Prepare the DS Server. In AM 6, 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 admin UI 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 AM admin UI 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 Back up configurations (AM 7 and later) or How do I make a backup of configuration data in AM 6.x?
2. Connect to AM using Amster, for example: $ ./amster am> connect --interactive https://am.example.com:8443/am 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: 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 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"
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 Back up configurations (AM 7 and later) or How do I make a backup of configuration data in AM 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 in AM 7 and later: $ ./ssoadm update-server-cfg -s default -u uid=amAdmin,ou=People,dc=am,dc=forgerock,dc=org -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 admin UI (All versions) fails for amAdmin user

FAQ: Installing and using ssoadm in AM

Core Token Service (CTS)

Tune the CTS

Related Training

N/A

Related Issue Tracker IDs

N/A