Installing OpenAM Tools

OpenAM tools are found in .zip files where you unpacked the archive of the entire package, such as ~/Downloads/openam. A list and description of these files follows.

SSOAdminTools-15.2.1.zip

Administration tools: ampassword, ssoadm, and amverifyarchive

See "To Set Up Administration Tools".

SSOConfiguratorTools-15.2.1.zip

Configuration and upgrade tools, alternatives to using the GUI configuration wizard

See "To Set Up Configuration Tools".

To Set Up Administration Tools

  1. Verify that OpenAM is installed and running before proceeding.

  2. Verify that the JAVA_HOME environment variable is set properly:

    $ echo $JAVA_HOME
/path/to/jdk

  3. Create a file system directory to unpack the tools:

    $ mkdir -p /path/to/openam-tools/admin

  4. Unpack the tools:

    $ cd /path/to/openam-tools/admin
$ unzip ~/Downloads/openam/SSOAdminTools-{openam-version}.zip

  5. Add --acceptLicense to the java command at the end of the setup or setup.bat script if you want to auto-accept the license agreement and suppress the license acceptance screen to the user:

    $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" \
                    -cp "$CLASSPATH" com.sun.identity.tools.bundles.Main \
                    --acceptLicense

  6. (Optional) 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

  7. Run the setup utility (setup.bat on Windows), providing paths to the directories where OpenAM configuration files are located, and where debug and log information will be located:

    $ ./setup
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: OpenAM version and date

    After setup, the tools are located under a directory named after the instance of OpenAM:

    $ ls openam/bin/
ampassword  amverifyarchive  ssoadm

    On Windows, these files are .bat scripts.

  8. (Optional) If your web container uses a self-signed certificate as described in "To Set Up OpenAM With HTTPS and Self-Signed Certificates" in the Administration Guide, then the ssoadm command will not trust the certificate when connecting to OpenAM over HTTPS, or when OpenAM connects to the configuration store over LDAPS.

    To allow the ssoadm command to trust the certificate, add the -D"javax.net.ssl.trustStore=/path/to/tomcat/conf/keystore.jks" option to the ssoadm or ssoadm.bat script before using the script.

    The option should be set before the call to com.sun.identity.cli.CommandManager at the end of the script:

    $ tail -2 /path/to/openam-tools/admin/openam/bin/ssoadm
    -D"javax.net.ssl.trustStore=/path/to/tomcat/conf/keystore.jks" \
    com.sun.identity.cli.CommandManager "$@"

    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.

  9. (Optional) 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 "$@"

  10. Check that the ssoadm command works properly:

    1. Create a text file, for example $HOME/.pwd.txt, containing the OpenAM administrative user’s password string in cleartext on a single line.

    2. Make the text file read-only:

      $ chmod 400 $HOME/.pwd.txt

    3. Run the ssoadm command to list the configured servers:

      $ cd /path/to/openam-tools/admin/openam/bin/
$ ./ssoadm list-servers -u amadmin -f $HOME/.pwd.txt
http://openam.example.com:8080/openam

  11. If desired, enable the ssoadm.jsp page as described in "OpenAM ssoadm.jsp" in the Administration Guide.

    You can run most (but not all) of the ssoadm subcommands from the ssoadm.jsp page in OpenAM after the page has been enabled.

  12. If you have deployed OpenAM in a site configuration, edit the ssoadm (ssoadm.bat on Windows) script to map the site URL to the OpenAM 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 OpenAM server against which you set up the ssoadm command.

    The ssoadm command is dependent on the OpenAM 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 OpenAM server against which you set up the ssoadm command is at http://openam.example.com:8080/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=http://openam.example.com:8080/openam"

    Repeat this step for each OpenAM 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 OpenAM server.

To Set Up Configuration Tools

  1. Verify the JAVA_HOME environment variable is properly set.

    $ echo $JAVA_HOME
/path/to/jdk

  2. Create a file system directory to unpack the tools.

    $ mkdir -p /path/to/openam-tools/config

  3. Unpack the tools from where you unzipped OpenAM.

    $ cd /path/to/openam-tools/config
$ unzip ~/Downloads/openam/SSOConfiguratorTools-15.2.1.zip
Archive:  ~/Downloads/openam/SSOConfiguratorTools-15.2.1.zip
   creating: legal-notices/
  inflating: legal-notices/LICENSE.DOM-software.html
  inflating: legal-notices/NOTICE.resolver.txt
  inflating: legal-notices/LICENSE.DOM-documentation.html
        ... (more output) ...
 extracting: lib/xml-apis-2.11.0.jar
 extracting: openam-configurator-tool-15.2.1.jar
 extracting: lib/servlet-api-2.5.jar

  4. Configure OpenAM server in a silent mode by using the openam-configurator-tool-15.2.1.jar tool after you deploy the .war file.

    OpenAM server must be deployed and running, but not configured yet, when you use the tool.

    The openam-configurator-tool-15.2.1.jar relies on a properties file to specify the configuration for the OpenAM server. The following example shows the equivalent of a default configuration, which installs OpenAM to run as HTTP.

    If you want implement HTTPS, see the next step.

    $ cp sampleconfiguration config.properties
$ vi config.properties
$ $ grep -v "^#" config.properties | grep -v "^$"
SERVER_URL=http://openam.example.com:8080
DEPLOYMENT_URI=/openam
BASE_DIR=/home/openam/openam
locale=en_US
PLATFORM_LOCALE=en_US
AM_ENC_KEY=
ADMIN_PWD=password
AMLDAPUSERPASSWD=secret12
COOKIE_DOMAIN=openam.example.com
ACCEPT_LICENSES=true
DATA_STORE=embedded
DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER=openam.example.com
DIRECTORY_PORT=50389
DIRECTORY_ADMIN_PORT=4444
DIRECTORY_JMX_PORT=1689
ROOT_SUFFIX=dc=openam,dc=forgerock,dc=org
DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD=password

    When the OpenAM server .war file is deployed and running, you can configure it by using the tool with the properties file.

    $ java -jar openam-configurator-tool-{openam-version}.jar --file config.properties
Checking license acceptance...License terms accepted.
Checking configuration directory /home/openam/openam....Success.
Installing OpenAM configuration store...Success RSA/ECB/OAEPWithSHA1AndMGF1...
Extracting OpenDJ, please wait...Complete
Running OpenDJ setupSetup command: --cli --adminConnectorPort 4444
 --baseDN dc=openam,dc=forgerock,dc=org --rootUserDN cn=Directory Manager
 --ldapPort 50389 --skipPortCheck --rootUserPassword xxxxxxx --jmxPort 1689
 --no-prompt --doNotStart --hostname openam.example.com ...
...Success
Installing OpenAM configuration store in /home/openam/openam/... ...Success.
Creating OpenAM suffixImport+task+ ... ...Success
Tag swapping schema files....Success.
Loading Schema opendj_config_schema.ldif...Success.

...

...Success.
Reinitializing system properties....Done
Registering service dashboardService.xml...Success.

...

Configuring system....Done
Configuring server instance....Done
Creating demo user....Done
Creating Web Service Security Agents....Done
Setting up monitoring authentication file.
Configuration complete!

  5. To configure HTTPS, you create a properties file and include the SERVER_URL property with the HTTPS URL and set the DIRECTORY_SSL to SIMPLE as follows:

    $ cp sampleconfiguration config.properties
$ vi config.properties
$ $ grep -v "^#" config.properties | grep -v "^$"
SERVER_URL=https://openam.example.com:1443
DEPLOYMENT_URI=/openam
BASE_DIR=/home/openam/openam
locale=en_US
PLATFORM_LOCALE=en_US
AM_ENC_KEY=
ADMIN_PWD=password
AMLDAPUSERPASSWD=secret12
COOKIE_DOMAIN=openam.example.com
ACCEPT_LICENSES=true
DATA_STORE=embedded
DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER=openam.example.com
DIRECTORY_PORT=50389
DIRECTORY_ADMIN_PORT=4444
DIRECTORY_JMX_PORT=1689
ROOT_SUFFIX=dc=openam,dc=forgerock,dc=org
DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD=password

  6. Then, when the OpenAM .war file is deployed and the server is running, configure the server to use HTTPS using the openam-configurator-tool-15.2.1.jar tool with the properties file as follows.

    java '-Djavax.net.ssl.trustStore=PATH_TO_JKS_TRUSTSTORE' \
      -jar openam-configurator-tool-15.2.1.jar \
      --file config.properties

For additional information about the command-line tool, see the reference documentation for configurator.jar(1) in the Reference.