The OpenAM-11.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-11.0.0.war /path/to/tomcat/webapps/openam.war

   You change the file name to openam.war when deploying in Tomcat so that the deployment URI is /openam.

   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 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. Provide different passwords for the default OpenAM administrator, amadmin, and default Policy Agent users.

   

3. 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 Console.

   

If you are unhappy with your configuration and want to start over from the beginning, follow these steps.

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

   The following example shuts down 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, also 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. Provide a password having at least 8 characters for the OpenAM Administrator, amadmin.

   

3. Make sure the server settings are valid for your configuration.

   

   Server URL

   Provide a valid URL to the base of your OpenAM web container, including a fully qualified domain name (FQDN).

   In a test environment, you can fake 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.

4. 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 or DSEE deployment, you can choose to 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.

   When you create a new OpenAM custom configuration that uses an external LDAP directory server for the configuration data store, you must use a root suffix DN with at least two domain components, such as dc=example,dc=com.

5. 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 a directory service already provisioned 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 on which the directory listens 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 are stored

   Login ID

   Directory administrator user DN. The administrator must be capable of updating schema and user data.

   Password

   Password for the directory administrator user

6. 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. 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 Setting Up OpenAM Session Failover.

   

   It is possible to set up a site after initial installation and configuration. Doing so is described in the chapter on Setting Up OpenAM Session Failover.

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

   

8. Check the summary screen, and if necessary click Previous to return to earlier screens if necessary to fix configuration errors.

   

   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.

   

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

   

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

   

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

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

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 the exposes a single URL as an entry point to the site.

Follow these steps to configure a server to belong 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 as the Server URL the URL of the first OpenAM server in the site.

   The directory used to store configuration data should belong to 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 have the configurator set up 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 you did 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.

You can deploy OpenAM server without OpenAM console by performing the following steps.

1. Deploy the OpenAM-ServerOnly-11.0.0.war file in your container.

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

   $ cp OpenAM-ServerOnly-11.0.0.war /path/to/tomcat/webapps/coreonly.war

2. Browse to the configuration application, such as http://openam.example.com:8080/coreonly/, and configure OpenAM core services as in Procedure 2.4, "To Configure OpenAM".

3. After configuration, restrict permissions to the configuration directory, such as $HOME/coreonly/ where $HOME corresponds to the user who runs the web container. Prevent other users from accessing files in the configuration directory.

1. Make sure OpenAM is installed and running before proceeding.

2. Make sure the JAVA_HOME environment variable is properly set.

   $ 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-11.0.0.zip

5. (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

6. Run the setup utility (setup.bat on Windows), providing the path to the directory where OpenAM configuration files are located, and where you want debug and log information to be located.

   $ ./setup
   Path to config files of OpenAM server [/home/mark/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.

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

8. Check that ssoadm works properly.

   $ echo password > /tmp/pwd.txt
   $ chmod 400 /tmp/pwd.txt
   $ cd /path/to/openam-tools/admin/openam/bin/
   $ ./ssoadm list-servers -u amadmin -f /tmp/pwd.txt
   
   http://openam.example.com:8080/openam

   The ssoadm commands can also be run from ssoadm.jsp in OpenAM, for example at http://openam.example.com:8080/openam/ssoadm.jsp, once the page has been enabled as described in the section on OpenAM ssoadm.jsp in the Administration Guide in the Administration Guide.

   Not all of the sub-commands available through the ssoadm command are available on the ssoadm.jsp web page.

9. (Optional) If you connect to OpenAM over SSL (HTTPS), the ssoadm by default tries to trust the certificate based on the CA certificates in the Java cacerts truststore. This might not work for your deployment.

   If the SSL certificate configured for the container where you deployed OpenAM was not signed by a recognized CA then the SSL connection process fails. For example, if you used a self-signed certificate as described in the Administration Guide procedure, To Set Up OpenAM With HTTPS on Tomcat in the Administration Guide, then the ssoadm command cannot trust that certificate by default. To allow the ssoadm command to trust the certificate, edit the ssoadm (ssoadm.bat on Windows) script as follows.

   Add two additional options to the java command in the script to identify the proper trust store and trust store password, depending on how you set up SSL. The following example points to the key store in which Tomcat holds the self-signed certificate that it presents when establishing an HTTPS connection.

   -D"javax.net.ssl.trustStore=/path/to/tomcat/conf/keystore.jks"
    -D"javax.net.ssl.trustStorePassword=changeit"

   If the ssoadm command cannot access the server key store in this way, set up your own trust store and import the server certificate using the Java keytool command.

10. 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 a com.iplanet.am.naming.map.site.to.server system property option of the java command 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 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. Make sure the JAVA_HOME environment variable is properly set.

   $ echo $JAVA_HOME
   /path/to/jdk

2. Unpack the tools from where you unzipped OpenAM.

   $ cd /path/to/openam-tools/config
   $ unzip ~/Downloads/openam/SSOConfiguratorTools-11.0.0.zip
   Archive:  ~/Downloads/openam/SSOConfiguratorTools-11.0.0.zip
     inflating: README
     inflating: sampleconfiguration
     inflating: sampleupgrade
    extracting: openam-configurator-tool-11.0.0.jar
    extracting: openam-upgrade-tool-11.0.0.jar
     inflating: license.txt

   Set up configuration files based on the sampleconfiguration example, and then apply the configuration to a deployed OpenAM .war file using the following command.

   $ java -jar openam-configurator-tool-11.0.0.jar -f config.file

   The config.file is set up by default to use the embedded data store with OpenAM installed on server1.example.com. You must edit the file before using it, as described in the OpenAM Reference for configurator.jar in the Reference.

1. Copy the OpenAM-DistAuth-11.0.0.war file into the webapps/ directory.

   cp ~/Downloads/openam/OpenAM-DistAuth-11.0.0.war
    /path/to/tomcat/webapps

2. Check that you see the initial DAS configuration screen in your browser.

1. Configure the DAS using the agent profile to connect to OpenAM.

   

   Most DAS configuration choices require no clarification. Hints for equivocal parameters follow.

   Debug Level

   Default is error. Other options include error, warning, message, and off.

   Encryption Key

   Do not change the password encryption key.

   Application User Name

   The DAS uses this identity, such as UrlAccessAgent, to authenticate to OpenAM.

   Application User Password

   The DAS uses this password to authenticate to OpenAM.

2. Login through the DAS to access OpenAM services.

   For testing, you can login as user demo, password changeit.

   

   When the /openam/idm/EndUser page is inside the firewall, and therefore not visible to users outside, redirect the browser after successful login to a page that exists. One way to do this is to use the goto parameter in the URL.

   https://das.example.com/das/UI/Login?goto=absolute-successful-redirect-URL

   On successful login, your browser stores an AMDistAuthConfig cookie that identifies the DAS.

3. Restrict permissions to the configuration for the DAS under the $HOME/FAMDistAuth directory of the user who runs the web container where you deployed the service.

   The configuration file name ends in AMDistAuthConfig.properties.

   If you deploy multiple DAS servers, you can configure them to forward requests to each other based on the AMDistAuthConfig cookie by setting the com.sun.identity.distauth.cluster property in this file. The following example lines are wrapped to fit on the page, but you put the entire property on a single line in the configuration file.

   com.sun.identity.distauth.cluster=
    http://das.example.com:8080/das/UI/Login,
    http://das2.example.com:8080/das/UI/Login

4. If your deployment includes multiple OpenAM servers, then edit the DAS configuration file, $HOME/FAMDistAuth/*AmDistAuthConfig.properties, to include X-Forwarded-For in the list of openam.retained.http.request.headers in the Reference.

   Example: openam.retained.http.request.headers=X-DSAMEVersion,X-Forwarded-For

   This ensures the authoritative OpenAM authentication server gets the client IP address in this header of the forwarded HTTP request. You can also add the header to the list for the openam.retained.http.headers property to have OpenAM copy the header to the response.

5. Some application servers such as JBoss 7 mount the content of the deployed .war file in a temporary location that can change on restart. To make sure that the DAS can find its bootstrap configuration in this case, specify the path to the bootstrap configuration file as a Java runtime option for the DAS, as in the following example. The property to set is openam.das.bootstrap.file.

   -Dopenam.das.bootstrap.file=/home/openam/FAMDistAuth/AMDistAuthConfig.properties

   You must make sure that the value of the option corresponds to the path to the correct AMDistAuthConfig.properties file.

Before you set up SFO, first configure OpenAM in a site configuration with a load balancer as the entry point to the site. The most expedient way to configure the site is to set it up during the initial OpenAM configuration. However, you may already have a working instance before realizing that multiple instances are necessary. The following steps walk you through setting up the site configuration for the first OpenAM server.

Once you have set up a site for the first OpenAM server, see To Add a Server to a Site for instructions on configuring subsequent servers in the site.

1. Login to OpenAM Console as amadmin, and then browse to Configuration > Servers and Sites > Sites.

2. Click New, and on the New Site page enter the site name, and set the Primary URL to the load balancer URL that is the entry point for the site, such as https://lb.example.com/openam.

   The site URL is the URL to the load balancer in front of your OpenAM servers in the site. For example, if your load balancer listens for HTTPS on host lb.example.com and port 443, with OpenAM under /openam, then your site URL is https://lb.example.com/openam.

3. Click Save to keep the site configuration.

4. Under Configuration > Servers and Sites > Server, click the link to the server configuration.

5. On the server configuration General tab page, set the Parent Site to the name of the site you just created, and then click Save to keep your changes.

   At this point the server is part of the site you have configured.

If you did not set up the site during initial configuration, first follow the instructions in Procedure 7.1, "To Configure a Site with a First OpenAM Server", and then follow all the steps below.

1. For each OpenAM server in the site, select Configuration > Servers and Sites > Servers > Server Name, and then set Parent Site to the site you created before saving your work.

2. In an OpenAM site, the server that authenticated a user is the server that continues to manage that user's session, unless the server is no longer available. Therefore, you should use sticky load balancing. To do so, configure your load balancer to inspect the value of the amlbcookie so that it can determine which OpenAM server should receive the client request.

   As your load balancer depends on the amlbcookie value, on each OpenAM server console in the site, select Configuration > Servers and Sites > Servers > Server Name > Advanced, makes sure that com.iplanet.am.lbcookie.value is unique. By default the value of the amlbcookie is set to the server ID for the OpenAM instance.

   Note

   When using SSL, the approach requires that you either terminate SSL on the load balancer and re-encrypt traffic from the load balancer to the OpenAM servers.

   If you must change amlbcookie values to make them unique, then your changes take effect after you restart the OpenAM server. (To check, login to the console and check the cookie value in your browser.)

3. Restart each OpenAM server or the web containers where the OpenAM servers run so that all configuration changes take effect.

Session failover requires a site configuration with one or more servers and OpenDJ as a configuration store (embedded or external).

If you did not configure session persistence and availability during initial configuration, first complete the steps in Procedure 7.2, "To Configure Site Load Balancing", 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 you are not using OpenDJ server, 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. Activate the Session Persistence and High Availability Failover Enabled option.

5. Click Add to save your work.

After you have deployed and configured OpenAM core services, you have at least two, perhaps three or 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/