Set 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_HOME environment variable is set properly:
```
$ echo $JAVA_HOME
/path/to/jdk
```
Create a file system directory to unpack the tools:
```
$ mkdir -p /path/to/openam-tools/admin
```

Unpack the tools:

$ cd /path/to/openam-tools/admin
$ unzip ~/Downloads/openam/AM-SSOAdminTools-5.1.3.27.zip

If you use IBM Java, add -D"amCryptoDescriptor.provider=IBMJCE" and -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:

$ tail setup
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 --acceptLicense option if you want to auto-accept the license agreement and suppress the license acceptance screen to the user.

How do I create the truststore?

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 Prepare the truststore, 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 details, refer to To Share Self-Signed Certificates.

When using self-signed certificates (in non-production environments, for example), you can configure the ssoadm command to trust all server certificates. Learn more in How do I configure ssoadm to trust all certificates? in the 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 outputs a message similar to the following:

Connect Error: No operational connection factories available

If you receive 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:

$ ls openam/bin/
ampassword  amverifyarchive  ssoadm

On Windows, these files are .bat scripts.

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"
....

Add the truststore_path, truststore_password, and truststore_type variables 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"
....

If you use IBM Java, add -D"amCryptoDescriptor.provider=IBMJCE" and -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.CommandManager at 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:

$ cd /path/to/openam-tools/admin/openam/bin/
$ ./ssoadm list-servers --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org --password-file $HOME/.pwd.txt
https://openam.example.com:8443/openam

The value for the --adminid parameter is the universal ID of an administrative user.

Administrative users are listed in the com.sun.identity.authentication.super.user or com.sun.identity.authentication.special.users advanced 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.json file, and find the value for the configStoreList/baseDN property.

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.server system 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):

-D"com.iplanet.am.naming.map.site.to.server=https://lb.example.com:443/openam=https://openam.example.com:8443/openam"

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.