Setting Up Administration Tools
AM provides a set of administration tools that are now deprecated in favor of Amster. They are part of the AM distributable file.
The ssoadm tool requires access to the AM configuration files and therefore must be installed on the same host as AM.
Verify that AM is installed and running before proceeding.
Verify that the
JAVA_HOMEenvironment variable is set properly:
Create a file system directory to unpack the tools:
mkdir -p /path/to/openam-tools/admin
Unpack the tools:
(Optional) If you use IBM Java, add
-D"amKeyGenDescriptor.provider=IBMJCE"options to the setup or setup.bat script before you install the tools.
The options should be set for the java command at the end of the script:
CLASSPATH="$CLASSPATH:resources" $JAVA_HOME/bin/java -D"load.config=yes" \ -D"help.print=$help_print" \ -D"path.AMConfig=$path_AMConfig" \ -D"path.debug=$path_debug" \ -D"path.log=$path_log" \ -D"amCryptoDescriptor.provider=IBMJCE" \ -D"amKeyGenDescriptor.provider=IBMJCE" \ -cp "$CLASSPATH" \ com.sun.identity.tools.bundles.Main
Run the setup utility (setup.bat on Windows) providing the location, password, and type of the truststore containing the public certificate of the DS configuration store.
Optionally, include the
--acceptLicenseoption if you want to auto-accept the license agreement and suppress the license acceptance screen to the user.
Even though you may have other truststores containing the public certificate of the configuration store, ForgeRock recommends that you use a truststore specifically for the ssoadm command.
To create it, follow the steps in "To Create a Truststore for AM", but do not configure the new truststore in the container. You will configure it in the ssoadm command script later.
If the container where AM runs is configured for secure connections and is using self-signed certificates, import that public certificate into the new truststore, too. For more information, see "To Share Self-Signed Certificates".
When using self-signed certificates, for example, in non-production environments, you can configure the ssoadm command to trust all server certificates. For more information, see Q. How do I configure ssoadm to trust all certificates? in the ForgeRock Knowledge Base.
You will also need to provide the paths to the directories where AM configuration files are located, and where the ssoadm debug and log information will be located. For example:
./setup --truststore-path /my/ssoadm/truststore --truststore-password changeit --truststore-type JKS --acceptLicense
Path to config files of OpenAM server [/home/user/openam]: Debug Directory [/path/to/openam-tools/admin/debug]: Log Directory [/path/to/openam-tools/admin/log]: The scripts are properly setup under directory: /path/to/openam-tools/admin/openam Debug directory is /path/to/openam-tools/admin/debug. Log directory is /path/to/openam-tools/admin/log. The version of this tools.zip is: version and date The version of your server instance is: ForgeRock Access Management version, Build, and date
If the setup utility cannot connect to the configuration store, it will show a message similar to the following:
Connect Error: No operational connection factories available
If you see this message, check that the truststore exists in the specified location, that it contains the configuration store certificate, and that the user running the setup utility can change directories to the specified location and open/read the file.
After setup, the tools are located under a directory named after the instance of AM:
ampassword amverifyarchive ssoadm
On Windows, these files are
Edit the ssoadm script and configure the truststore containing the certificate of the configuration store. This truststore may also contain the certificate to connect to AM using SSL, if needed.
In the script, look for the following lines:
.... TRUSTSTORE="-Djavax.net.ssl.trustStore=$truststore_path" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStorePassword=$truststore_password" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStoreType=$truststore_type" ....
truststore_typevariables above the lines you found:
truststore_path=/my/ssoadm/truststore truststore_password=changeit truststore_type=JKS TRUSTSTORE="-Djavax.net.ssl.trustStore=$truststore_path" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStorePassword=$truststore_password" TRUSTSTORE="$TRUSTSTORE -Djavax.net.ssl.trustStoreType=$truststore_type" ....
(Optional) If you use IBM Java, add
-D"amKeyGenDescriptor.provider=IBMJCE"options to the ssoadm or ssoadm.bat script before using the script.
The options should be set before the call to
com.sun.identity.cli.CommandManagerat the end of the script:
tail -3 /path/to/openam-tools/admin/openam/bin/ssoadm
-D"amCryptoDescriptor.provider=IBMJCE" \ -D"amKeyGenDescriptor.provider=IBMJCE" \ com.sun.identity.cli.CommandManager "$@"
Check that the ssoadm command works properly:
Create a text file, for example
$HOME/.pwd.txt, containing the AM administrative user's password string in cleartext on a single line.
Make the text file read-only:
chmod 400 $HOME/.pwd.txt
Run the ssoadm command to list the configured servers:
./ssoadm list-servers --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org --password-file $HOME/.pwd.txt
The value for the
--adminidparameter is the universal ID of an administrative user.
Administrative users are listed in the
com.sun.identity.authentication.special.usersadvanced properties, under Configure > Server Defaults > Advanced.
The default super-user account is
uid=amAdmin,ou=People,%ROOT_SUFFIX%. To check your %ROOT_SUFFIX% value, go to the
/path/to/openam/config/boot.jsonfile, and find the value for the
If you have deployed AM in a site configuration, edit the ssoadm (ssoadm.bat on Windows) script to map the site URL to the AM server URL.
To do this, set the
com.iplanet.am.naming.map.site.to.serversystem property as a java command option in the script. The option takes the following form:
-D"com.iplanet.am.naming.map.site.to.server=lb-url=openam-url[, other-lb-url=openam-url ...]"
The property maps each lb-url key to an openam-url value, where lb-url is the URL to a site load balancer, and openam-url is the URL to the AM server against which you set up the ssoadm command.
The ssoadm command is dependent on the AM server against which you set it up, so always map site load balancer URLs to that server's openam-url.
For example, if your site is behind
https://lb.example.com:443/openam, and the AM server against which you set up the ssoadm command is at
https://openam.example.com:8443/openam, then add the following property to the java command (all on one line without spaces):
Repeat this step for each AM server in your site configuration. You can install all your instances of ssoadm on the same host, but in each case the command should manage only one AM server.