The OpenAM-13.0.0.war file contains OpenAM server with OpenAM Console. How you deploy the .war file depends on your web application container.

1. Deploy the .war file on your container.

   For example, copy the file to deploy on Apache Tomcat.

   $ cp OpenAM-13.0.0.war /path/to/tomcat/webapps/openam.war
      

   Note

   You change the file name to something other than openam.war when deploying in Tomcat so that the deployment URI is not /openam. For helpful hints on avoiding obvious deployment defaults, see Section 27.1, "Avoiding Obvious Defaults" in the Administration Guide.

   Important

   In order to be properly configured, OpenAM requires a deployment URI with a non-empty string after /. Do not deploy OpenAM at the root context. Do not rename the .war file to ROOT.war before deploying on Tomcat, for example.

   It can take several seconds for OpenAM to be deployed in your container.

2. Browse to the initial configuration screen, for example at http://openam.example.com:8080/openam.

   

The default configuration option configures the embedded OpenDJ server using default ports. If the ports are already in use, OpenAM uses free ports as both configuration store and identity store.

The default configuration sets the cookie domain based on the fully qualified domain name (FQDN) of the system. For an FQDN openam.example.com, the cookie domain is set to .example.com.

Configuration settings are saved to the home directory of the user running the web application container in a directory named after the deployment URI. In other words if OpenAM is deployed under /openam, then the configuration is saved under $HOME/openam/.

1. In the initial configuration screen, click Create Default Configuration under Default Configuration.

2. Review the software license agreement. If you agree to the license, click "I accept the license agreement", and then click Continue.

   

3. Provide different passwords for the default OpenAM administrator, amadmin, and default Policy Agent users.

   

4. When the configuration completes, click Proceed to Login, and then login as the OpenAM administrator with the first of the two passwords you provided.

   

   After successful login, OpenAM redirects you to OpenAM Realms.

   

If you need to delete your configuration and start the process from the beginning, follow these steps.

1. Stop the OpenAM web application to clear the configuration held in memory.

   The following example shuts down Apache Tomcat (Tomcat) for example.

   $ /path/to/tomcat/bin/shutdown.sh
   Password: 
   Using CATALINA_BASE:   /path/to/tomcat
   Using CATALINA_HOME:   /path/to/tomcat
   Using CATALINA_TMPDIR: /path/to/tomcat/temp
   Using JRE_HOME:        /path/to/jdk/jre
   Using CLASSPATH:
          /path/to/tomcat/bin/bootstrap.jar:/path/to/tomcat/bin/tomcat-juli.jar

2. Delete OpenAM configuration files, by default under the $HOME of the user running the web application container.

   $ rm -rf $HOME/openam $HOME/.openamcfg

   When using the internal OpenAM configuration store, this step deletes the embedded directory server and all of its contents. This is why you stop the application server before removing the configuration.

   If you use an external configuration store, delete the entries under the configured OpenAM suffix (by default dc=openam,dc=forgerock,dc=org).

3. Restart the OpenAM web application.

   The following example starts the Tomcat container.

   $ /path/to/tomcat/bin/startup.sh
   Password: 
   Using CATALINA_BASE:   /path/to/tomcat
   Using CATALINA_HOME:   /path/to/tomcat
   Using CATALINA_TMPDIR: /path/to/tomcat/temp
   Using JRE_HOME:        /path/to/jdk/jre
   Using CLASSPATH:
          /path/to/tomcat/bin/bootstrap.jar:/path/to/tomcat/bin/tomcat-juli.jar

1. In the initial configuration screen, click Create New Configuration under Custom Configuration.

2. Read the license agreement. If you agree to the license, click "I agree to the license agreement", and then click Continue.

3. On the Default User Password page, provide a password with at least eight characters for the OpenAM Administrator, amadmin.

   

4. Verify that the server settings are valid for your configuration.

   

   Server URL

   Provide a valid URL to the base of your OpenAM web container, including a FQDN.

   In a test environment, you can simulate the FQDN by adding it to your /etc/hosts as an alias. The following excerpt shows lines from the /etc/hosts file on a Linux system where OpenAM is installed.

   127.0.0.1 localhost.localdomain localhost
   ::1 localhost6.localdomain6 localhost6
   127.0.1.1 openam openam.example.com

   Cookie Domain

   Starts with a dot (.).

   Platform Locale

   Supported locales include en_US (English), de (German), es (Spanish), fr (French), ja (Japanese), ko (Korean), zh_CN (Simplified Chinese), and zh_TW (Traditional Chinese).

   Configuration Directory

   Location on server for OpenAM configuration files. OpenAM must be able to write to this directory.

5. In the Configuration Store screen, you can accept the defaults to allow OpenAM to store configuration data in an embedded directory. The embedded directory can be configured separately to replicate data for high availability if necessary.

   

   You can also add this OpenAM installation to an existing deployment, providing the URL of the site. See Procedure 2.5, "To Add a Server to a Site" for details.

   Alternatively, if you already manage an OpenDJ deployment, you can store OpenAM configuration data in your existing directory service. You must, however, create the suffix to store configuration data on the directory server before you configure OpenAM. OpenAM does not create the suffix when you use an external configuration store.

6. In the User Store screen, you configure where OpenAM looks for user identities.

   OpenAM must have write access to the directory service you choose, as it adds to the directory schema needed to allow OpenAM to manage access for users in the user store.

   

   User Data Store Type

   If you have already provisioned a directory service with users in a supported user data store, then select that type of directory from the options available.

   SSL/TLS Enabled

   To use a secure connection, check this box, then make sure the port you define corresponds to the port the directory server listens to for StartTLS or SSL connections. When using this option you also need to make sure the trust store used by the JVM running OpenAM has the necessary certificates installed.

   Directory Name

   FQDN for the host housing the directory service.

   Port

   LDAP directory port. The default for LDAP and LDAP with StartTLS to protect the connection is port 389. The default for LDAP over SSL is port 636. Your directory service might use a different port.

   Root Suffix

   Base distinguished name (DN) where user data is stored.

   Login ID

   Directory administrator user DN. The administrator must be able to update the schema and user data.

   Password

   Password for the directory administrator user.

7. In the Site Configuration screen, you can set up OpenAM as part of a site where the load is balanced across multiple OpenAM servers.

   If you have a site configuration with a load balancer, you can enable session high availability persistence and failover.^[1] OpenAM then stores sessions across server restarts, so that users do not have to login again.

   If you then add additional servers to this OpenAM site, OpenAM performs session failover, storing session data in a directory service that is shared by different OpenAM servers. The shared storage means that if an OpenAM server fails, other OpenAM servers in the site have access to the user's session data and can serve requests about that user. As a result, the user does not have to log in again. If session failover is important for your deployment, also follow the instructions in Chapter 7, "Setting Up OpenAM Session Failover".

   

   It is possible to set up a site after initial installation and configuration, as is described in Chapter 7, "Setting Up OpenAM Session Failover".

8. In the Agent Information screen, provide a password with at least eight characters to be used by policy agents to connect to OpenAM.

   

9. Check the summary screen, and if necessary, click Previous to return to earlier screens to fix any configuration errors as needed.

   

   After you click Create Configuration in the summary screen, configuration proceeds, logging progress that you can read in your browser and later, in the installation log. The process ends, and OpenAM shows the Proceed to Login prompt.

   

10. When the configuration completes, click Proceed to Login, and then login as the OpenAM administrator, amadmin.

    

    After login, OpenAM redirects you to the OpenAM Realms page.

    

    You can also access OpenAM Console by browsing to the Console URL, such as, http://openam.example.com:8080/openam/console.

11. Restrict permissions to the configuration directory (by default, $HOME/openam, where $HOME corresponds to the user who runs the web container). Prevent other users from accessing files in the configuration directory.

12. If you specified the Other User Data Store option in the User Data Store Settings screen, you must index several attributes in your external identity repository. See Procedure 1.3, "To Index External Identity Repository Attributes" for more information.

High availability requires redundant servers in case of failure. With OpenAM, you configure an OpenAM site with multiple servers in a pool behind a load balancing service that exposes a single URL as an entry point to the site.

Follow these steps to configure a server to an existing site.

1. In the initial configuration screen, under Custom Configuration, click Create New Configuration.

2. In the first screen, enter the same password entered for the OpenAM Administrator, amadmin, when you configured the first server in the site.

3. Configure server settings as required.

   The cookie domain should be identical to that of the first server in the site.

4. In the configuration store screen, select Add to Existing Deployment, and enter the URL of the first OpenAM server in the site.

   The directory used to store configuration data should use the same directory service used for this purpose by other OpenAM servers in the site. If you use the embedded OpenDJ directory server, for example, you can set up the configurator for data replication with embedded directory servers used by other servers in the site.

   Settings for the user store are then shared with the existing server, so the corresponding wizard screen is skipped.

5. In the site configuration screen, select Yes and enter the same site configuration details as for the first server in the site.

   Settings for agent information are also shared with the existing server, so the corresponding wizard screen is skipped.

6. In the summary screen, verify the settings you chose, and then click Create Configuration.

7. When the configuration process finishes, click Proceed to Login, and then login as the OpenAM administrator to access OpenAM Console.

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-13.0.0.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 you connect to OpenAM over HTTPS, and if your web container uses a self-signed certificate, then the ssoadm command will not be able to trust the certificate.

   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 "$@"

   Note

   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 Section 1.3, "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.

    Important

    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.

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-13.0.0.zip
   Archive:  ~/Downloads/openam/SSOConfiguratorTools-13.0.0.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-13.0.0.jar
    extracting: lib/servlet-api-2.5.jar

4. Configure OpenAM server in a silent mode by using the openam-configurator-tool-13.0.0.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-13.0.0.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-13.0.0.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-13.0.0.jar tool with the properties file as follows.

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

Session failover requires an OpenAM site configuration with a Core Token Service.

If you did not configure session persistence and availability during initial configuration, first complete the steps in the procedure, Procedure 4.2, "To Configure Site Load Balancing for Deployments With Stateful Sessions", and then follow these steps.

1. In the OpenAM console for one of the servers in the site, under Configuration > Global, click Session.

2. Under Secondary Configuration Instance, click New.

   If the server is not part of a site, or if the configuration server does not support the Core Token Service, the New button is grayed out.

3. In the Add Sub Configuration page, check that the Name is set to the name of the site.

4. To activate the Session Persistence and High Availability Failover option, check the Enabled box.

5. To ensure that local OpenAM instances resolve sessions from the Core Token Service session store instead of crosstalk, check the Reduce Crosstalk Enabled box. For more information about crosstalk, see the section, Chapter 4, "Installation Considerations for Multiple Servers".

   Do not disable reduced crosstalk unless advised to do so by ForgeRock Technical Support.

6. Set reduced crosstalk options.

   Session logout/destroy broadcasting enables notification to all servers in an OpenAM site when a user logs out or her session is destroyed by the OpenAM server. The broadcast notifications are in addition to normal session logout/destroy notifications sent to interested clients and servers.

   Without session logout/destroy broadcasting, it is possible for a user to log out from one OpenAM server and then access her session on another server during the brief window between the logout and session store replication. Enabling session logout/destroy broadcasting ensures that logged out and destroyed sessions have the correct state on all OpenAM servers.

   • Select Disabled if you do not want the OpenAM server to broadcast session logout/destroy messages. Session logout/destroy broadcasting is disabled by default. Disabling broadcasting is suitable when you do not need the highest level of security. Disable broadcasting when you do not expect users to maliciously attempt to access logged out or destroyed sessions.

   • Specify one of the two broadcast options to achieve a higher level of security, at a cost of incurring additional network I/O. Select "Broadcast only to local site servers" if your session store supports a single OpenAM site. Select "Broadcast to servers in all sites" if your session store supports multiple OpenAM sites.

   The Reduced Crosstalk Purge Delay option specifies the amount of time (in minutes) before sessions are purged from OpenAM servers after the server receives session logout/destroy broadcast notification. The delay ensures that sessions are in memory during the time between session logout/destruction and session store replication.

   The default purge delay is 1 minute, which should be adequate unless session store replication is abnormally slow on your network.

7. Click Add to save your work.

   OpenAM enables session failover immediately after you save the configuration changes. It is not necessary to restart the servers in your site.

After you have deployed and configured OpenAM core services, you may have at least two to four locations where OpenAM files are stored on your system.

You remove the internal OpenAM configuration store when you follow the procedure below. If you used an external configuration store, you can remove OpenAM configuration data after removing all the software.

1. Shut down the web application container in which you deployed OpenAM.

   $ /etc/init.d/tomcat stop
   Password:
   Using CATALINA_BASE:   /path/to/tomcat
   Using CATALINA_HOME:   /path/to/tomcat
   Using CATALINA_TMPDIR: /path/to/tomcat/temp
   Using JRE_HOME:        /path/to/jdk/jre
   Using CLASSPATH:       /path/to/tomcat/bin/bootstrap.jar:
    /path/to/tomcat/bin/tomcat-juli.jar
      

2. Unconfigure OpenAM by removing configuration files found in the $HOME directory of the user running the web application container.

   For a full install of OpenAM core services, configuration files include the following.

   • The configuration directory, by default $HOME/openam. If you did not use the default configuration location, then check in the OpenAM console under Configuration > Servers and Sites > Server Name > General > System > Base installation directory.

   • The hidden file that points to the configuration directory.

     For example, if you are using Apache Tomcat as the web container, this file could be $HOME/.openamcfg/AMConfig_path_to_tomcat_webapps_openam_ OR $HOME/.openssocfg/AMConfig_path_to_tomcat_webapps_openam_.

   $ rm -rf $HOME/openam $HOME/.openamcfg
      

   Or:

   $ rm -rf $HOME/openam $HOME/.openssocfg
      

   Note

   At this point, you can restart the web container and configure OpenAM anew if you only want to start over with a clean configuration rather than removing OpenAM completely.

   If you used an external configuration store, you must also remove the configuration manually from your external directory server. The default base DN for the OpenAM configuration is dc=openam,dc=forgerock,dc=org.

3. Undeploy the OpenAM web application.

   For example, if you are using Apache Tomcat as the web container, remove the .war file and expanded web application from the container.

   $ cd /path/to/tomcat/webapps/
   $ rm -rf openam.war openam/