OpenAM 10.2.0-SNAPSHOT Installation Guide

The openam-server-10.2.0-SNAPSHOT.war file contains all OpenAM server components and samples. 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/openam-server-10.2.0-SNAPSHOT.war 
       /path/to/tomcat/webapps/openam.war

   Note

   By adding openam.war to the end of the path, the name of the .war file will be changed from openam-server-only-10.2.0-SNAPSHOT.war to openam.war to make deployment easier.

2. Check that you see the initial configuration screen in your browser at openam.example.com:8080/openam.

   Note

   You should NOT use localhost domain for accessing OpenAM, not even for testing purposes, because OpenAM strongly relies on browser cookies. Also the chosen domain name should contain at least 2 '.' (dot) characters, like openam.example.com. This gives your instance a domain, example, and a subdomain, openam. Sub-domains provide an extra layer of organization for different department or types of users or clients. It also provides a level of control over your top- level domain that you would not have if you used .com or .org.

   

   
   [D]

The default configuration option will basically configure the embedded OpenDJ instance on default ports (if the ports are already in use, OpenAM will look for a free port) as both configuration store and identity store. The install will create a standalone OpenAM instance using the subset of the fully qualified hostname as the cookie domain. In the example .example.com the cookie domain is set to .example.com.

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.

   

   
   [D]

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

   

   
   [D]

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

   The following example shuts down Tomcat configured as described above.

   $ /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/jdk1.6/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

   Note

   When using the internal OpenAM configuration store, this step deletes the embedded directory server and all of its contents. You should always stop the application server before removing the configuration files. In case you're using external configuration store make sure you 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 restarts the Tomcat container.

   $ /etc/init.d/tomcat start
   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/jdk1.6/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.

   

   
   [D]

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

   

   
   [D]

   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 to reach an existing OpenAM instance. Procedure 2.5, “Configuring an Additional Instance” provides information on setting up an additional instance of OpenAM.

   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.

   Note

   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. The root suffix must be dc. You will not be able to move to the next configuration screen if both of these conditions are not met.

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.

   

   
   [D]

   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.

   For your first OpenAM installation, you can accept the defaults. If you have a load balancer, you can enable session high availability persistence. This will store sessions in case of a server failure, so that when the server is restored, users will be returned to their sessions without having to login again. If you would like to enable session high availability persistence or if you plan to setup additional instances, enter the Site Name, Load Balancer URL, and click the Enable Session HA Persistence and Failover.

   

   
   [D]

   If you plan to set up an additional instance but are not ready yet, you do not have to set it up now. The site configuration can be set up during configuration of your additional instances.

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

   

   
   [D]

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

   

   
   [D]

9. Restrict permissions to the configuration directory (by default $HOME/openam, where $HOME corresponds to the user who runs the web container).

When an additional OpenAM instance is necessary (usually for Setting Up OpenAM Session Failover [SFO]), it is configured separately from the first instance.

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

2. Enter the same password entered during the first instance configuration for the OpenAM Administrator, amadmin.

   Note

   If you make a mistake at any time during the configuration, click on the Previous button and the OpenAM Configurator will return to the previous screen. When you click Next, the original default values will appear.

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

   If you make changes to the default values, an x mark or a check mark will indicate if the added value is acceptable. For example, you cannot add additional instances under the same configuration directory as the first instance.

   

   
   [D]

4. Click on Add to Existing Deployment?. Enter the Server URL of the first instance, for example http://openam.example.com:18080/openam. You should be able to accept the default settings once your Server URL has been verified.

   

   
   [D]

5. Select Yes to add the load balancer with each additional instance. It is alright if you did not add the load balancer with the first instance. The SFO chapter describes how to add the load balancer to the first instance.

   Enter the Site Name, for example openamlb, and the Load Balancer URL.

   

   
   [D]

6. Verify the Configurator Summary Details.

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

You can deploy OpenAM core services without including the console if you install the console elsewhere, or if you plan to perform all configuration using ssoadm for example.

1. Deploy the openam-server-only-10.2.0-SNAPSHOT.war file on your container.

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

   $ cp ~/Downloads/openam/openam-server-only-10.2.0-SNAPSHOT.war 
       /path/to/tomcat/webapps/coreonly.war

   Note

   By adding coreonly.war to the end of the path, the name of the .war file will be changed from openam-server-only-10.2.0-SNAPSHOT.war to coreonly.war so the deployment URI will be /coreonly.

2. Browse to the console application, for example http://host.example.com:8080/coreonly/, and configure OpenAM core services as if you were deploying with a full version.

3. Restrict permissions to the $HOME/coreonly configuration directory, where $HOME corresponds to the user who runs the web container.

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/jdk1.6

3. Unpack the tools from where you unzipped OpenAM.

   $ cd /path/to/openam-tools/admin
   $ unzip ~/Downloads/openam/
     openam-distribution-ssoadmintools-10.2.0-SNAPSHOT.zip
   ...
     inflating: template/windows/bin/amverifyarchive.bat.template
     inflating: template/windows/bin/ssoadm.bat.template

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

5. Check that ssoadm works properly.

   $ umask 366
   $ echo password > /tmp/pwd.txt
   $ 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.

   Not all the commands are available on ssoadm.jsp, however this limitation is not present for the command line tool.

6. If you connect to OpenAM over SSL (HTTPS), and the SSL certificate was not signed by a CA whose certificate is found in the Java cacerts truststore (for example, you used a self-signed certificate as described in the Administration Guide procedure, To Set Up OpenAM With HTTPS on Tomcat), then edit the ssoadm (ssoadm.bat on Windows) script such that ssoadm recognizes the certificate.

   Add two additional options to the java command in the script to identify the proper truststore and truststore password, depending on how you set up SSL.

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

7. 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/jdk1.6

2. Unpack the tools from where you unzipped OpenAM.

   $ cd /path/to/openam-tools/config
   $ unzip ~/Downloads/openam/
     openam-distribution-ssoadmintools-10.2.0-SNAPSHOT.zip
   Archive:  ~/Downloads/openam/openam-distribution-ssoadmintools-10.2.0-SNAPSHOT.zip
     inflating: ssoadm.template
     inflating: ssoadm.bat.template
     inflating: ampassword.template
     inflating: ampassword.bat.template
     inflating: amverifyarchive.template

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

The diagnostic tool, ssodtool.sh (ssodtool.bat on Windows), works in both graphical and console mode.

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

   $ echo $JAVA_HOME
   /path/to/jdk1.6

2. Unpack the tools from where you unzipped OpenAM.

   $ cd /path/to/openam-tools/diagnostic
   $ unzip ~/Downloads/openam/openam-distribution-ssoadmintools-10.2.0-SNAPSHOT.zip
   ...
     inflating: services/webcontainer/service.xml
     inflating: ssodtool.bat
     inflating: ssodtool.sh

   You can start the graphical user interface by using the tools without options, or in console mode using the ssodtool.sh --console command.

1. Copy the openam-distauth-10.2.0-SNAPSHOT.war file into the webapps/ directory.

   cp ~/Downloads/openam/
       openam-distauth-10.2.0-SNAPSHOT.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.

   

   
   [D]

   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.

   

   
   [D]

   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

Rather than changing the default pages, customize your own copy.

1. Change to the config/auth directory where you deployed OpenAM.

   $ cd /path/to/tomcat/webapps/openam/config/auth

2. Copy the default files and optionally the localized files to suffix[_locale]/html, where suffix is the value of the RDN of the configuration suffix, such as openam if you use the default configuration suffix dc=openam,dc=forgerock,dc=org, and the optional locale is, for example, jp for Japanese, or zh_CN for Simplified Chinese.

   The following example copies the files for the Top-Level Realm (/) for a custom French locale.

   $ mkdir -p openam/html
   $ cp -r default/* openam/html
   $ mkdir -p openam_fr/html
   $ cp -r default_fr/* openam_fr/html

   See How OpenAM Looks Up UI files for details.

As for the top-level realm, customize your copy rather than the default pages.

1. Change to the config/auth directory where you deployed OpenAM.

   $ cd /path/to/tomcat/webapps/openam/config/auth

2. Depending on which locale you want to customize, copy the default files and optionally the localized files to suffix[_locale]/services/realm/html.

   The following example copies the files for a custom French locale and a realm named ventes.

   $ mkdir -p openam/html/ventes/html
   $ cp -r default/* openam/services/ventes/html
   $ mkdir -p openam_fr/services/ventes/html
   $ cp -r default_fr/* openam_fr/services/ventes/html

The .jsp files from the default/ directory reference the images used in the OpenAM pages, and retrieve localized text from the .xml files. Thus you customize appearance through the .jsp files, being careful not to change the functionality itself. You customize the localized text through the .xml files.

1. Modify appearance if you must by editing the .jsp, image, and CSS files without changing any of the JSP tags that govern how the pages work.

2. Modify the localized text, using UTF-8 without escaped characters, by changing only the original text strings in the .xml files.

   For example, to change the text in the default OpenAM login screen in the top-level realm for the French locale, edit openam_fr/html/DataStore.xml.

3. If necessary, restart OpenAM or the web container to test the changes you have made.

   The following screen shot shows a customized French login page where the string Nom d'utilisateur has been replaced with the string Votre identifiant, and the string Mot de passe has been replaced with the string Votre mot de passe in openam_fr/html/DataStore.xml.

   

   
   [D]

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, where OpenAM can manage and replicate server configuration for availability. However, you may already have a working instance before realizing that multiple instances are necessary. The following steps walk you through setting up the load balancer for the first instance.

1. In the OpenAM console for the first instance of the site, select Configuration > Servers and Sites and click on the first server under Servers.

2. Under site Site click on Parent Site and select the load balancer.

3. Click on Save.

If you did not set up the site during initial configuration, then follow all the steps below.

1. In the OpenAM console for one of the servers in the site, select Configuration > Servers and Sites > Sites > New..., and then create a new site.

   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 on host lb.example.com and port 8080, with OpenAM under /openam, then your site URL is http://lb.example.com:8080/openam.

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

3. If you want to use sticky load balancing, configure your load balancer to inspect the value of the amlbcookie to 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, or that you 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.)

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

Enabling session failover in OpenAM requires a site configuration with one or more servers and OpenDJ as a configuration store (embedded or external). If these are not setup before you begin the process, the New... button will be greyed out.

The following steps walk you through configuring an additional instance.

1. In the OpenAM console for one of the servers in the site, select Configuration > Global > Session > and New... for the Secondary Configuration Instance.

2. Verify that the additional instance appears in the Name text box and that Session Persistence and High Availability Failover Enabled is checked.

3. Save your changes.

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/jdk1.6/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/

4. If you have stored a download or unpacked version of OpenAM software on your system, you can now remove the files.

   If you cannot find the original .zip, search for files named openam-*.zip.

   $ find . -name "openam-*.zip"
   ./Downloads/openam
   $ rm ./Downloads/openam