Guide showing you how to install OpenAM. OpenAM provides open source Authentication, Authorization, Entitlement and Federation software.


This guide shows you how to install core OpenAM services for access and federation management. Unless you are planning a throwaway evaluation or test installation, read the Release Notes before you get started.

1. Who Should Use this Guide

This guide is written for anyone installing OpenAM to manage and to federate access to web applications and web based resources.

This guide covers the install, upgrade, and removal (a.k.a. uninstall) procedures that you theoretically perform only once per version. This guide aims to provide you with at least some idea of what happens behind the scenes when you perform the steps.

You do not need to be an OpenAM wizard to learn something from this guide, though a background in access management and maintaining web application software can help. You do need some background in managing services on your operating systems and in your application servers. You can nevertheless get started with this guide, and then learn more as you go along.

2. Formatting Conventions

Most examples in the documentation are created in GNU/Linux or Mac OS X operating environments. If distinctions are necessary between operating environments, examples are labeled with the operating environment name in parentheses. To avoid repetition file system directory names are often given only in UNIX format as in /path/to/server, even if the text applies to C:\path\to\server as well.

Absolute path names usually begin with the placeholder /path/to/. This path might translate to /opt/, C:\Program Files\, or somewhere else on your system.

Command-line, terminal sessions are formatted as follows:

$ echo $JAVA_HOME

Command output is sometimes formatted for narrower, more readable output even though formatting parameters are not shown in the command.

Program listings are formatted as follows:

class Test {
    public static void main(String [] args)  {
        System.out.println("This is a program listing.");

3. Accessing Documentation Online

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

4. Using the Site

The site has links to source code for ForgeRock open source software, as well as links to the ForgeRock forums and technical blogs.

If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRock support professionals will get in touch to help you.

Chapter 1. Installing OpenAM Core Services

This chapter covers tasks required to install OpenAM core services, and to ensure they run properly. It includes instructions on preparing your application server to run OpenAM, preparing your identity repository to handle OpenAM identities, deploying component .war files, installing OpenAM administration tools, and performing post-installation configuration.

To manage access to web resources on other servers, you can install policy agents that provide tight integration with OpenAM. See the Policy Agent Installation Guide for instructions on installing OpenAM agents in supported web servers and Java EE application containers.

1.1. Preparing Prerequisite Software

OpenAM core services require the following prerequisite software installed before you begin OpenAM installation.

  • A Java 6 runtime environment

    $ java -version
    java version "1.6.0_29"
    Java(TM) SE Runtime Environment (build 1.6.0_29-b11-402-11D50)
    Java HotSpot(TM) 64-Bit Server VM (build 20.4-b02-402, mixed mode)
  • A supported application server as the deployment container

    See the Release Notes in the Release Notes for a list.

    OpenAM core services require a minimum JVM heap size of 1 GB, and a permanent generation size of 256 MB. Apply the following JVM options before start your application server.

    -Xmx1024m -XX:MaxPermSize=256m

    If a Java Security Manager is enabled for your deployment container, add permissions before installing OpenAM.

    OpenAM examples here use Apache Tomcat as the deployment container. Tomcat is installed on, and listens on the default ports, with no Java Security Manager enabled. The script /etc/init.d/tomcat manages the service at system startup and shutdown.

    # tomcat
    # chkconfig: 345 95 5
    # description: Manage Tomcat web application container
    export CATALINA_HOME
    export JAVA_HOME
    JAVA_OPTS="-Xmx1024m -XX:MaxPermSize=256m"
    export JAVA_OPTS
    case "${1}" in
      /bin/su mark -c "${CATALINA_HOME}/bin/"
      exit ${?}
      /bin/su mark -c "${CATALINA_HOME}/bin/"
      exit ${?}
      echo "Usage:  $0 { start | stop }"
      exit 1
  • A supported identity repository for user identity data

    See the Release Notes in the Release Notes for a list. If you plan to use OpenAM for evaluation or testing, definitely use the embedded LDAP server as a configuration store and identity repository. ForgeRock also recommends using the embedded LDAP server as the configuration store when you have four or fewer instances of OpenAM in production.

    Examples here use OpenDJ as the identity repository. OpenDJ is installed on, and listens on the following ports.

    • Port 1389 for LDAP requests and StartTLS

    • Port 1636 for LDAP requests over SSL

    • Port 4444 for administrative traffic

    The script /etc/init.d/opendj, created with the OpenDJ create-rc-script command, manages the service at system startup and shutdown.

    # chkconfig: 345 95 5
    # description: Control the OpenDJ Directory Server
    # Set the path to the OpenDJ instance to manage
    export INSTALL_ROOT
    cd ${INSTALL_ROOT}
    # Determine what action should be performed on the server
    case "${1}" in
      /bin/su mark -c "${INSTALL_ROOT}/bin/start-ds --quiet"
      exit ${?}
      /bin/su mark -c "${INSTALL_ROOT}/bin/stop-ds --quiet"
      exit ${?}
      /bin/su mark -c "${INSTALL_ROOT}/bin/stop-ds --restart --quiet"
      exit ${?}
      echo "Usage:  $0 { start | stop | restart }"
      exit 1

    The sample data loaded into OpenDJ are taken from the file, Example.ldif, that you can download.

    See the OpenDJ Installation Guide for detailed installation instructions.

1.2. Obtaining OpenAM Software

Download OpenAM releases from At the download location you find links to stable releases, nightly builds for testing, previous releases, and also OpenAM policy agent releases.

For each release of the OpenAM core services, you can download the entire package as a .zip archive, only the OpenAM .war file, only the administrative tools as a .zip archive, or only the OpenAM source code used to build the release.

After you unzip the archive of the entire package, you get an opensso directory including a README, a set of license files, and the following directories. See the File Layout reference in the Reference for details.


The deployable .war file as well as the tools and files required to create any specialized .war files you deploy.


Javadoc API specifications for the public APIs exposed by OpenAM


The lightweight service provider implementations that you can embed in your Java EE or ASP.NET application to enable it to use federated access management


Resources for integrating OpenAM with third-party access and identity management software


Schema and index definitions for use with external LDAP identity repositories


Client SDK and policy agent libraries


Location for patches to apply to OpenAM


Sample source files demonstrating how to use the OpenAM client SDK


OpenAM tools for managing SSO, configuring deployed .war files, patching deployed .war files, managing sessions, and diagnosing deployment issues


OpenAM service and default delegation policy configuration files

1.3. Install the OpenAM Web Application

The deployable-war/opensso.war file contains all OpenAM server components and samples. How you deploy the .war file depends on your web application container.

Procedure 1.1. To Deploy OpenAM on Tomcat
  1. Copy the .war file to the directory where web applications are stored.

    $ cp deployable-war/opensso.war /path/to/tomcat/webapps/openam.war
  2. Check that you see the initial configuration screen in your browser at


    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

    Initial OpenAM configuration screen
Procedure 1.2. To Configure OpenAM With Defaults (For Testing)

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.

  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.

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

    OpenAM first login
Procedure 1.3. To Delete an OpenAM Configuration Before Redeploying
  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
    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:
  2. Delete OpenAM configuration files, by default under the $HOME of the user running the web application container.

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


    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=opensso,dc=java,dc=net).

  3. Restart the OpenAM web application.

    The following example restarts the Tomcat container.

    $ /etc/init.d/tomcat start
    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:
Procedure 1.4. To Configure OpenAM
  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.

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

    OpenAM server settings
    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. localhost.localdomain localhost
    ::1 localhost6.localdomain6 localhost6 openam
    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.

    Alternatively, if you already manage an OpenDJ or DSEE deployment, you can choose to store OpenAM configuration data in your existing directory service.

  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.

    OpenAM user store settings
    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 truststore used by the JVM running OpenAM has the necessary certificates installed.

    Directory Name

    FQDN for the host housing the directory service


    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 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, accept the defaults.

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

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

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

Chapter 2. Installing OpenAM Tools

OpenAM tools are found in the tools/ directory where you unpacked the archive of the entire package.


Quick description of the tools .zip files. Each tools .zip also includes a specific README.


Administration tools: ampassword, ssoadm and amverifyarchive


Tools for command line installation, upgrade, and initial configuration


Tool to check for problems with your deployment and configuration


Session failover utilities. Installation for these tools is described in the chapter on Setting Up OpenAM Session Failover.

Procedure 2.1. To Set Up Administration Tools
  1. Make sure the JAVA_HOME environment variable is properly set.

    $ echo $JAVA_HOME
  2. Unpack the tools from where you unzipped OpenAM.

    $ cd /path/to/admin/tools
    $ unzip /path/to/OpenAM/tools/
      inflating: template/windows/bin/amverifyarchive.bat.template
      inflating: template/windows/bin/ssoadm.bat.template
  3. 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/admin/tools/debug]:
    Log Directory [/path/to/admin/tools/log]:
    The scripts are properly setup under directory: /path/to/admin/tools/openam
    Debug directory is /path/to/admin/tools/debug.
    Log directory is /path/to/admin/tools/log.
    The version of this is: (2011-July-11 00:05)
    The version of your server instance is: (2011-July-11 00:05)

    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.

  4. Check that ssoadm works properly.

    $ umask 366
    $ echo password > /tmp/pwd.txt
    $ openam/bin/ssoadm list-servers -u amadmin -f /tmp/pwd.txt

    The ssoadm commands can also be run from ssoadm.jsp in OpenAM, for example at, 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 the commands are available on ssoadm.jsp, however this limitation is not present for the command line tool.

  5. (Optional) 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 in the Administration Guide), 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.

  6. (Optional) If you have deployed OpenAM in a site configuration, edit the ssoadm (ssoadm.bat on Windows) script to map the site name to servers.

    You add a property to the java command in the script.

    lb-url=openam-url[,lb-url=openam-url ...]"

    Notice that the mapping is a comma separated list of server URLs, openam-url, in the site with the load balancer URL, lb-url. For example, if your site is behind, and the OpenAM servers are at and, then you add the following property to the java command (without line breaks).

Procedure 2.2. To Set Up Configuration Tools
  1. Make sure the JAVA_HOME environment variable is properly set.

    $ echo $JAVA_HOME
  2. Unpack the tools from where you unzipped OpenAM.

    $ unzip /path/to/OpenAM/tools/ 
    Archive:  /path/to/OpenAM/tools/
      inflating: README.setup
      inflating: configurator.jar
      inflating: sampleconfiguration
      inflating: sampleupgrade
      inflating: upgrade.jar

    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 You must edit the file before using it, as described in the OpenAM Reference for configurator.jar in the Reference.

Procedure 2.3. To Set Up Diagnostic Tool

The diagnostic tool, (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
  2. Unpack the tools from where you unzipped OpenAM.

    $ unzip /path/to/OpenAM/tools/
      inflating: services/webcontainer/service.xml
      inflating: ssodtool.bat

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

Chapter 3. Installing OpenAM Core Only

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.

Procedure 3.1. To Create the Core Services .war File
  1. Unpack the opensso.war file into a temporary directory.

    $ mkdir -p /tmp/headless ; cd /tmp/headless
    $ jar xf /path/to/OpenAM/deployable-war/opensso.war
  2. Create the headless.war file.

    $ cd /path/to/OpenAM/deployable-war
    $ sh -s /tmp/headless --type noconsole -w headless.war
Procedure 3.2. To Deploy the Core Services On Tomcat
  1. Put the headless.war you created in the Tomcat webapps/ directory.

    $ mv headless.war /path/to/tomcat/webapps/
  2. Browse to the console application, for example, and configure OpenAM core services as if you were deploying with a full version.

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

Chapter 4. Installing OpenAM Distributed Authentication

When you need to prevent end users from having direct access to the service URLs OpenAM uses to manage access, you can deploy the distributed authentication service (DAS) in your DMZ, leaving OpenAM core services behind the firewall that end users cannot access.

You complete the following stages in deploying the DAS web service.

  1. Make sure the cookie domain for the DAS is configured in OpenAM under Configuration > System > Platform.

  2. Make sure the realms used have a Realm/DNS alias for the DAS configured in OpenAM under Access Control > Realm Name > General.

  3. Create the .war file for the DAS using OpenAM software.

  4. Deploy the DAS .war file into your web application container.

    How you deploy the DAS .war file depends on your web application container. The procedure in this section shows how to deploy on Apache Tomcat.

  5. Configure the DAS UI to access OpenAM core services.

  6. Configure your firewall to allow end user access to the DAS.

    Firewall configuration is not described here.

Procedure 4.1. To Create the DAS .war File
  1. Unpack the opensso.war file into a temporary directory.

    $ mkdir -p /tmp/das ; cd /tmp/das
    $ jar xf /path/to/OpenAM/deployable-war/opensso.war
  2. Create the das.war file.

    $ cd /path/to/OpenAM/deployable-war
    $ sh --staging /tmp/das --type distauth --warfile das.war
Procedure 4.2. To Deploy the DAS on Tomcat
  1. Put the das.war you created in the Tomcat webapps/ directory.

    $ mv das.war /path/to/tomcat/webapps/
  2. Check that you see the initial DAS configuration screen in your browser.

Procedure 4.3. To Configure the DAS
  1. Configure the DAS using the agent profile to connect to OpenAM.

    Completed DAS configuration screen

    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.

    Successfully logged in through the DAS

    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.

    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

    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.


Chapter 5. Installing OpenAM Client SDK Samples

The full download of OpenAM comes with a Java Client SDK and samples located in samples/ where you unpacked the file. The Developer's Guide in the Developer's Guide describes how to use the Java SDK, and the OpenAM Java SDK API Specification provides a reference to the public APIs.

To install the Client SDK, unzip where you want to install the SDK and examples.

$ cd samples/ ; unzip -oq
Procedure 5.1. To Deploy the Sample Web Application

The sample web application deploys in your container to show you the client SDK samples in action.

  1. Deploy the .war in your Java web application container such as Apache Tomcat or JBoss.

    $ cp war/opensso-client-jdk15.war /path/to/tomcat/webapps/client.war
  2. Browse to the location where you deployed the client, and configure the application to access OpenAM using the application user name, UrlAccessAgent, and password configured when you set up OpenAM.

    Sample web app configuration screen

    The sample client writes configuration information under $HOME/OpenSSOClient/, where $HOME is that of the user running the web application container.

  3. Verify that you have properly configured the sample web application.

    1. On the Client Samples page, click Access Management Samples.

    2. In another browser tab page of the same browser instance, login to OpenAM as the OpenAM Administrator, amadmin.

      This signs you into OpenAM, storing the cookie in your browser.

    3. On the Samples tab page, click the link under Single Sign On Token Verification Servlet.

      If the sample web application is properly configured, you should see something like the following text in your browser.

      SSOToken host name:
      SSOToken Principal name: id=amadmin,ou=user,o=openam
      Authentication type used: DataStore
      IPAddress of the host:
      SSO Token validation test succeeded
      The token id is AQIC5wM2LY4SfcyeA2UgS0dLJIb-xjJClrk_EIXBpdzh7RI.*AAJTSQACMDE.*
      Property: Company: Sun Microsystems
      Property: Country: USA
      User Attributes: {sunIdentityMSISDNNumber=[], mail=[],
       dn=[uid=amAdmin,ou=people,o=openam], givenName=[amAdmin],
       inetUserStatus=[Active], telephoneNumber=[], sn=[amAdmin],
       roles=[Top-level Admin Role], employeeNumber=[], postalAddress=[],
       iplanet-am-user-success-url=[], iplanet-am-user-failure-url=[],
       cn=[amAdmin], iplanet-am-user-alias-list=[]}
Procedure 5.2. To Build the Command-Line Sample Applications
  1. Compile the sample applications.

    $ cd sdk/
    $ sh scripts/
  2. Configure the samples to access OpenAM.

    $ sh scripts/
    Debug directory (make sure this directory exists): /tmp
    Application user (e.g. URLAccessAgent) password: secret12
    Protocol of the server: http
    Host name of the server:
    Port of the server: 8080
    Server's deployment URI: /openam
    Naming URL (hit enter to accept default value,
  3. Verify that you have properly configured the samples.

    $ sh scripts/
    Realm (e.g. /):
    Login module name (e.g. DataStore or LDAP): LDAP
    Login locale (e.g. en_US or fr_FR): en_US
    LDAP: Obtained login context
    User Name:bjensen
    Login succeeded.
    Logged Out!!

Chapter 6. Customizing the OpenAM End User Pages

When you deploy OpenAM to protect your web-based applications, users can be redirected to OpenAM pages for login and logout. ForgeRock provides pages localized for English, French, German, Spanish, Japanese, Korean, Simplified Chinese, and Traditional Chinese, but you might require additional language support for your organization.

Also, by default the end user pages have ForgeRock styling and branding. You likely want to change at least the images to reflect your organization. You might want to have different page customizations for different realms as well. This chapter address how to get started customizing OpenAM end user pages for your organizations and supported locales.

First you copy the pages to customize to the proper location, then you customize the files themselves.

Images in this example are located in /path/to/tomcat/webapps/openam/images/, and CSS in /path/to/tomcat/webapps/openam/css/. If you choose to modify images for your deployment, you can maintain the sizes to avoid having to customize page layout extensively.


The procedures below describe how to update a deployed version of OpenAM, so that you can see your changes without redeploying the application. This approach works for development as long as your web container does not overwrite changes. When developing with a web container that deploys OpenAM in a temporary location, such as JBoss or Jetty, restarting the container can overwrite your changes with the deployable .war content. For those web containers, you should also prepare a deployable .war containing your changes, and redeploy that file to check your work.

For production deployment you must package your changes in a custom OpenAM deployable .war file. To create a deployable .war, unpack the OpenAM .war file from /path/to/OpenAM/deployable-war into a staging directory, apply your changes in the staging directory, and use the or createwar.bat script to prepare the deployable .war.

Procedure 6.1. To Copy the Pages to Customize For the Top-Level Realm

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 opensso if you use the default configuration suffix dc=opensso,dc=java,dc=net, 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.

Procedure 6.2. To Copy the Pages to Customize For Another Realm

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
    $ cp -r default/* openam/services/ventes/html
    $ mkdir -p openam_fr/services/ventes/html
    $ cp -r default_fr/* openam_fr/services/ventes/html
Procedure 6.3. To Customize Files You Copied

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.

    Example customized OpenAM login page

6.1. How OpenAM Looks Up UI Files

This section provides a more complete description of how OpenAM looks up UI files.

OpenAM uses the following information to look up the UI files.

Configuration suffix RDN

When you set up the OpenAM to store its configuration in a directory server, you provide the distinguished name of the configuration suffix, by default dc=opensso,dc=java,dc=net, therefore, the relative distinguished name attribute value is opensso. If instead you set the configuration suffix to be o=openam, the RDN value is openam.

Client (browser) locale language

The client can specify a locale, which can consist of both a language and a territory, such as en_GB for British English. The language in this case is en.

Client (browser) locale territory

If the client local is en_GB, then the territory in this case is GB.

Platform locale language

The platform locale, defined for the platform where OpenAM runs, can also consist of both a language and a territory, such as hu_HU. In this example the platform locale language is hu for Hungarian.

Platform locale territory

If the platform locale is hu_HU, the platform locale territory is HU for Hungary.


Realms can be nested. OpenAM uses the nesting as necessary to look for files specific to a sub-realm before looking in the parent realm.

For all realms below the top level realm, OpenAM adds a services directory before the realm to the search path.

Client name

Client names identify the type of client. The default, html, is the only client name used unless client detection mode is enabled. When client detection mode is enabled, the client name can be different for mobile clients, for example.

File name

File names are not themselves localized. Thus Login.jsp has the same name for all locales, for example.

OpenAM tries first to find the most specific file for the realm and local requested, gradually falling back on less specific alternatives, then on other locales. The first and most specific location as follows.


Example 6.1. UI File Lookup

OpenAM looks up Login.jsp in the following order for a realm named realm, with the browser requesting en_GB locale, the platform locale being hu_HU, and the configuration suffix named o=openam. The client name used in this example is the generic client name html.


Chapter 7. Setting Up OpenAM Session Failover

This chapter covers setting up session failover when using multiple instances of OpenAM in a site configuration for high availability. The basic idea followed here is that you configure load balancing to be sticky, based on the value of an OpenAM cookie, amlbcookie, different for each OpenAM server. Should that server become unavailable, the load balancer fails client requests over to another OpenAM server. The other OpenAM server must then fail over the user session associated with the client.

Session failover uses a highly available data store for OpenAM session data, shared by OpenAM servers in a site configuration. When the OpenAM server where a user authenticated goes down, other OpenAM servers can read the user session information from the highly available store, so the user does not have to authenticate again. When the original OpenAM server becomes available again, it can also read session information from the store, and carry on serving users with active sessions.


Session failover is supported within a site or data center with a shared local area network. Session failover is not supported across sites and data centers linked by wide area networks (WAN). Latency over the WAN can cause issues with the underlying message queue, and therefore prevents reliable session failover.

Procedure 7.1. Before You Start

Before you set up session failover, 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 initial OpenAM configuration, where OpenAM can manage and replicate server configuration for availability. 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 and port 8080, with OpenAM under /openam, then your site URL is

  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. (Optional) 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 is unique. By default the value of the amlbcookie is set to the server ID for the OpenAM instance.


    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.

Procedure 7.2. To Prepare the Session Data Service

The session data service relies on Open Message Queue and Berkeley DB Java Edition. You set up the session failover service in a site cluster to serve as the highly available session data store.

  1. Install the session tools from on at least two, and generally not more than four, servers where you run OpenAM.[1]

    For example, you can install the session tools in the OpenAM configuration directory.

    $ cd $HOME/openam
    $ unzip /path/to/OpenAM/tools/
    $ ./setup
    Name of the directory to install the scripts (example: sfoscripts):sfoscripts
    The scripts are properly setup under directory: /home/user/openam/sfoscripts
    JMQ is properly setup under directory /home/user/openam/jmq
  2. Start the Message Queue broker in order to configure user accounts.

    $ cd jmq/imq/bin
    $ ./imqbrokerd -name aminstance -port 7777 &
  3. Change the default admin password from admin to something else.

    $ ./imqusermgr update -u admin -p password -i aminstance
    User repository for broker instance: aminstance
    Are you sure you want to update user admin? (y/n)[n] y
    User admin successfully updated.
  4. Disable the default guest account.

    $ ./imqusermgr update -u guest -a false -i aminstance
    User repository for broker instance: aminstance
    Are you sure you want to update user guest? (y/n)[n] y
    User guest successfully updated.
  5. Add a user for the session failover service.

    $ ./imqusermgr add -u openamuser -g admin -p secret12 -i aminstance
    User repository for broker instance: aminstance
    User openamuser successfully added.
  6. Create a password file for the session failover service.

    $ cd ../../../sfoscripts/bin/
    $ ./amsfopassword --encrypt secret12 --passwordfile /home/user/openam/mqpwd.txt
  7. Stop the broker you started on port 7777.

    $ fg
    ./imqbrokerd -name aminstance -port 7777 (wd: ~/openam/jmq/imq/bin)
    [05/Mar/2012:08:35:22 CET] [B1047]: Shutting down broker...
    [05/Mar/2012:08:35:22 CET] [B1077]: Broadcast good-bye to all connections ...
    [05/Mar/2012:08:35:22 CET] [B1078]: Flushing good-bye messages ...
    [05/Mar/2012:08:35:23 CET] [B1048]: Shutdown of broker complete.
  8. Configure the session failover service for the site.

    For each session tools installation, edit the /home/user/openam/sfoscripts/config/lib/amsfo.conf configuration file to change at least the USER_NAME, CLUSTER_LIST, and PASSWORDFILE parameters.

    USER_NAME should match the user you created for the session failover service.


    CLUSTER_LIST specifies the host:port combinations for all the session failover services you configure for the site.,

    PASSWORDFILE specifies the path to the password file you created.


    You can optionally set AMSESSIONDB_ARGS="-v" to log additional information.

Procedure 7.3. To Enable Session Failover

Enabling session failover at this point involves configuring OpenAM to use the session data store, and then starting services. Examples in this procedure show OpenAM running in Apache Tomcat.

  1. On one of the OpenAM servers in the site, login to the console, and then select Configuration > Global > Session > Instances > New... to set up session data store access.

    Provide a user name for the Session Store User, such as openamuser, with the same password you entered into the password file, and the Database Url is the host:port combination that you entered for the CLUSTER_LIST parameter.

    Be sure to Add the new instance, and then also Save your configuration changes. The configuration changes take effect after you restart OpenAM.

  2. Stop each OpenAM server in the site.

    $ /etc/init.d/tomcat stop
  3. Start each session data service in the cluster.

    $ cd /home/user/openam/sfoscripts/bin
    $ ./amsfo start

    By default, the log and session data store are located under /tmp/amsession/.

    $ tail -f /tmp/amsession/logs/amsessiondb.log
    Initializing and connecting to the Message Queue server ...
    Successfully started.
  4. Start each OpenAM server in the site.

    $ /etc/init.d/tomcat start

    Wait for each OpenAM server to start before starting another.

    $ tail -f /path/to/tomcat/logs/catalina.out
    INFO: Server startup in 26047 ms

    After OpenAM has started, you can test session failover.

[1] You install more than one instance of the session tools in case an instance crashes and must fail over to another instance. At the same time, session failover requires that messages be sent across the network from one instance to another to stay in sync in case of failover. If you install too many instances, however, then the increase in network traffic for synchronization can impair performance.

Chapter 8. Upgrading OpenAM Core Services

This chapter shows you how to patch and to upgrade OpenAM core services. See the Policy Agent Installation Guide for instructions on upgrading OpenAM agents.

This chapter uses Apache Tomcat in examples. If you use a different web application container for OpenAM, adapt the examples to your environment.


For complex and legacy deployments, ForgeRock can assist you through the upgrade process. Send mail to for more information.

Procedure 8.1. To Upgrade From OpenAM 9.5 Or Later

ForgeRock has considerably simplified OpenAM core services upgrade with respect to earlier versions. If you have already moved to OpenAM 9.5 or later, follow these steps.

  1. If you have customized end user OpenAM files for your deployment, build a new .war with the new version of OpenAM that includes your customizations.

  2. If OpenAM is running in a site deployment with multiple servers, configure your load balancer to take the OpenAM server out of the site pool during upgrade.

  3. Stop the container where OpenAM is running.

    $ /etc/init.d/tomcat stop
    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:
  4. Make a copy of the OpenAM configuration directory that was created at installation time.

    In the following example, the OpenAM configuration directory is $HOME/openam, where $HOME is the home directory of the user running the container where OpenAM is deployed.

    $ cd $HOME
    $ cp -r openam openam-orig

    Files in the hidden $HOME/.openssocfg/ directory are not changed during upgrade.

  5. Make a backup copy of the OpenAM configuration stored in your configuration store.

  6. Move the current OpenAM web application aside.

    $ cd /path/to/tomcat/webapps
    $ mv openam openam-orig ; mv openam.war openam.war.orig
  7. Deploy the new OpenAM in place of the old.

    $ cp /path/to/new/OpenAM/deployable-war/opensso.war openam.war
  8. If your container caches OpenAM files, clear out the cache.

    $ rm -rf /path/to/tomcat/work/Catalina/localhost/openam
  9. Start the container to run the new OpenAM.

    $ /etc/init.d/tomcat start
    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:
  10. In your browser, visit the location where OpenAM is deployed, such as, and then click Upgrade to OpenAM 10.0.0.

    Initial OpenAM upgrade screen
  11. In the Upgrading OpenAM screen, click Save Report to download an OpenAM Upgrade Report listing necessary configuration changes, and then click Upgrade.

    Save upgrade report window

    Log messages pertaining to upgrade of the embedded directory are written to the web container log.

  12. When upgrade completes, restart OpenAM or the container where it runs, and continue your work.

    In site deployments with multiple OpenAM servers using the embedded OpenDJ configuration store, you must keep the first upgraded server running when upgrading the others.

    This allows secondary servers to correctly replicate their embedded configuration stores with that of the first server you upgraded.

  13. If OpenAM is running in a site deployment with multiple servers, configure your load balancer to return the OpenAM server to the site pool.


You can use the upgrade.jar utility, installed from, to perform the upgrade configuration after you deploy the new OpenAM .war file.

Instead of upgrading the new OpenAM deployment through OpenAM console as described in the procedure above, edit the sampleupgrade properties file next to upgrade.jar to set the SERVER_URL and DEPLOYMENT_URI for your environment, and then run the upgrade.jar utility.

$ java -jar upgrade.jar --file sampleupgrade
Upgrade Complete.
Procedure 8.2. To Revert From OpenAM Upgrade

If you must revert from an upgraded version of OpenAM, then the quickest way to return to the earlier version is to restore all the earlier files. You also must return to an earlier version of the configuration store data.

  1. Stop OpenAM or the container where OpenAM is running.

  2. Restore the old version of OpenAM files, including the .war and the configuration directory.

  3. If your container caches OpenAM files, clear out the cache.

    $ rm -rf /path/to/tomcat/work/Catalina/localhost/openam
  4. Restore the earlier version of the configuration store data.

  5. (Optional) If you run OpenAM in Tomcat, remove files from the working directory where Tomcat has stored JSP files from the upgraded version.

    $ rm -fr /path/to/tomcat/work/Catalina/localhost/openam

    If you skip this step, you can see an error like the following when logging into the console after reverting to the older version.

    amConsole:10/29/2011 05:42:51:812 PM BST: Thread[http-8080-3,5,main]
    ERROR: ConsoleServletBase.onUncaughtException
    javax.servlet.ServletException: java.lang.NoClassDefFoundError:
            at org.apache.jasper.runtime.PageContextImpl.doHandlePageException
            at org.apache.jasper.runtime.PageContextImpl.handlePageException
            at org.apache.jsp.console.task.Home_jsp._jspService(
            at org.apache.jasper.runtime.HttpJspBase.service(
  6. Start the earlier version of OpenAM or the container where OpenAM runs.

Chapter 9. Removing OpenAM Software

This chapter shows you how to uninstall OpenAM core software. See the Policy Agent Installation Guide for instructions on removing OpenAM agents.

Procedure 9.1. To Remove OpenAM Core Software

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
    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:
  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/.openssocfg/AMConfig_path_to_tomcat_webapps_openam_.

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


    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=opensso,dc=java,dc=net.

  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"
    $ rm ./Downloads/

    If you cannot find the unpacked version, you might search for the directory named deployable-war.

    $ locate deployable-war/
    $ rm -rf /path/to/OpenAM
Read a different version of :