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.1.3.zip

Administration tools: ampassword, ssoadm, and amverifyarchive

SSOConfiguratorTools-15.1.3.zip

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

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.1.3.zip
    Archive:  ~/Downloads/openam/SSOConfiguratorTools-15.1.3.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.1.3.jar
     extracting: lib/servlet-api-2.5.jar
  4. Configure OpenAM server in a silent mode by using the openam-configurator-tool-15.1.3.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.1.3.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.1.3.jar tool with the properties file as follows.

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

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