# OpenAM 10.2.0-SNAPSHOT Installation Guide

Legal Notice

Publication date: June 19, 2013

Abstract

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

## Preface

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

Some items are formatted differently from other text, like filenames, commands, and literal values.

$echo Command line sessions are formatted with lines folded for easier reading. In HTML documents click the [-] image for a flat, copy-paste version. Click the [+] image for an expanded, line-wrapped version. > /dev/null In many cases, sections pertaining to UNIX, GNU/Linux, Mac OS X, BSD, and so forth are marked (UNIX). Sections pertaining to Microsoft Windows might be marked (Windows). To avoid repetition, however, 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/, which might translate to /opt/, C:\Program Files\, or somewhere else on your system. Unless you install from native packages, you create this location before you install. class Test { public static void main(String [] args) { System.out.println("This is a program listing."); } } ## 3. Accessing Documentation Online Core documentation, such as what you are now reading, aims to be technically accurate and complete with respect to the software documented. Core documentation therefore follows a three-phase review process designed to eliminate errors. The review process help to ensure that documentation you get with a stable release is technically accurate and complete. Fully reviewed, published core documentation is available at docs.forgerock.org. In-progress documentation can be found at each project site under the Developer Community projects page. The ForgeRock Community Wikis provide additional documentation. We encourage you to join the community, so that you can update the Wikis, too. ## 4. Joining the ForgeRock Community After you sign up to join the ForgeRock community, you can edit the Community Wikis, and also log bugs and feature requests in the issue tracker. If you have a question regarding a project but cannot find an answer in the project documentation or Wiki, browse to the Developer Community page for the project, where you can find details on joining the project mailing lists, and find links to mailing list archives. You can also suggest updates to documentation through the ForgeRock docs mailing list. The Community Wikis describe how to check out and build source code. Should you want to contribute a patch, test, or feature, or want to author part of the core documentation, first have a look on the ForgeRock site at how to get involved. ## Chapter 1. Preparing For Installation This chapter covers prerequisites for installing OpenAM software, including how to prepare your application server to run OpenAM, and how to prepare your identity repository to handle OpenAM identities. ## 1.1. Preparing a Fully-Qualified Domain Name OpenAM requires that you provide the fully-qualified domain name (FQDN) when you configure it. Before you set up OpenAM, be sure that your system has an FQDN such as openam.example.com. For evaluation purposes, you can give your system an alias using the /etc/hosts file on UNIX systems or %SystemRoot%\system32\drivers\etc\hosts on Windows. For deployment, make sure the FQDN is properly assigned for example using DNS. ## 1.2. Preparing Prerequisite Software OpenAM core services require that you install a Java runtime environment and an application container before you begin OpenAM installation. • A Java 6 runtime environment Check the output of java -version to make sure your the version is supported according to the Release Notes section on Java Requirements. • A supported application server as the deployment container See the Release Notes for a list. If a Java Security Manager is enabled for your deployment container, add permissions before installing OpenAM. • A supported identity repository for user identity data For evaluation you can use the embedded OpenDJ LDAP directory server, which ships as part of OpenAM and that you can install as part of the OpenAM configuration process. Evaluation does not therefore require a separate user data or configuration store. When moving to put OpenAM in production use a separate user data store in most cases. Also if you have more than four OpenAM servers in your production deployment, then use a separate LDAP directory server for the configuration store as well. See the Release Notes for a list of supported external stores. Examples in the documentation that show a separate user data repository use OpenDJ unless otherwise indicated. In such examples OpenDJ is installed on openam.example.com, 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. This script assumes you run OpenDJ as the user opendj. #!/bin/sh #... # chkconfig: 345 95 5 # description: Control the OpenDJ Directory Server # Set the path to the OpenDJ instance to manage INSTALL_ROOT="/path/to/OpenDJ" export INSTALL_ROOT cd${INSTALL_ROOT}

# Determine what action should be performed on the server
case "${1}" in start) /bin/su opendj -c "${INSTALL_ROOT}/bin/start-ds --quiet"
exit ${?} ;; stop) /bin/su opendj -c "${INSTALL_ROOT}/bin/stop-ds --quiet"
exit ${?} ;; restart) /bin/su opendj -c "${INSTALL_ROOT}/bin/stop-ds --restart --quiet"
exit ${?} ;; *) echo "Usage:$0 { start | stop | restart }"
exit 1
;;
esac


The Example.com 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.3. Obtaining OpenAM Software

• Enterprise Downloads has the latest stable version of OpenAM, including a .zip file with all of the OpenAM components, the .war file, OpenAM tools, the configurator, policy agents, OpenIG, and documentation. Please review the Software License and Subscription Agreement before using OpenAM in production.

• Builds has the nightly build, including a .zip file with all of the OpenAM components, the .war file, OpenAM tools, the configurator, policy agents, and the .NET Fedlet. Be aware that this is the working version of the trunk and should not be used in a production environment.

• Archives has all versions of OpenAM, from 9.5.1 to 10.0.1. It includes the .zip file with all of the OpenAM components, the .war file, OpenAM tools, the configurator, policy agents, the WSS policy agents, and the .NET Fedlet for all previous releases.

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

After you download the .zip file, create a new openam folder, and unzip the .zip file to access the content:

$cd ~/Downloads$ mkdir openam ; cd openam
$unzip ~/Downloads/openam-distribution-kit-10.2.0-SNAPSHOT.zip When you unzip the archive of the entire package, you get ldif, license, and legal directories in addition to the following files. openam-clientsdk-10.2.0-SNAPSHOT.jar The OpenAM Java client SDK library openam-distauth-10.2.0-SNAPSHOT.war The deployable .war file for distributed authentication openam-distribution-diagnostics-10.2.0-SNAPSHOT.zip The .zip file with the diagnostic tools to help troubleshoot deployment issue. openam-distribution-fedlet-unconfigured-10.2.0-SNAPSHOT.zip The .zip that contains the lightweight service provider implementations that you can embed in your Java EE or ASP.NET applications to enable it to use federated access management openam-distribution-ssoadmintools-10.2.0-SNAPSHOT.zip The .zip file that contains tools to manage OpenAM from the command line openam-distribution-ssoconfiguratortools-10.2.0-SNAPSHOT.zip The .zip file that contains tools to configure OpenAM from the command line openam-server-10.2.0-SNAPSHOT.war The deployable .war file openam-server-only-10.2.0-SNAPSHOT.war The deployable .war file when you want to deploy OpenAM server without the OpenAM console openam-example-clientsdk-cli-10.2.0-SNAPSHOT.zip The .zip file containing the Java client SDK command-line examples, and .jar files needed to run the examples. openam-example-clientsdk-war-10.2.0-SNAPSHOT.war The .war file containing Java client SDK examples in a web application. ## 1.4. Preparing Apache Tomcat OpenAM examples often use Apache Tomcat as the deployment container. Tomcat is installed on openam.example.com, 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. This script assumes you run OpenAM as the user openam. OpenAM core services require a minimum JVM heap size of 1 GB, and a permanent generation size of 256 MB. #!/bin/sh # # tomcat # # chkconfig: 345 95 5 # description: Manage Tomcat web application container CATALINA_HOME="/path/to/tomcat" export CATALINA_HOME JAVA_HOME=/path/to/jdk1.6 export JAVA_HOME CATALINA_OPTS="-Xmx1024m -XX:MaxPermSize=256m" export CATALINA_OPTS case "${1}" in
start)
/bin/su openam -c "${CATALINA_HOME}/bin/startup.sh" exit${?}
;;
stop)
/bin/su openam -c "${CATALINA_HOME}/bin/shutdown.sh" exit${?}
;;
*)
echo "Usage:  $0 { start | stop }" exit 1 ;; esac  ## 1.5. Preparing GlassFish v2 Before you deploy OpenAM, update these JVM options. These settings are accessible in the administration console under Application Server > JVM Settings > JVM Options. -server Use -server rather than -client. -XX:MaxPermSize=256m Set the permanent generation size to 256 MB. -Xmx1024m Make sure OpenAM has at least 1 GB heap. ## 1.6. Preparing OpenAM & JBoss 4 or 5 OpenAM must be able to store its configuration between restarts. If you plan to deploy OpenAM as a single archive file, then unpack the .war, edit WEB-INF/classes/bootstrap.properties to set the configuration.dir property to the location where OpenAM has write access to store its configuration. $ mkdir openam
$cd openam$ jar -xf ~/Downloads/openam/openam-server-10.2.0-SNAPSHOT.war
$vi WEB-INF/classes/bootstrap.properties$ grep ^config WEB-INF/classes/bootstrap.properties
configuration.dir=/home/jboss-user/openam

Also, OpenAM .jar libraries that conflict with JBoss libraries must be loaded first. Add a WEB-INF/jboss-web.xml to ensure this happens. (If you deploy the exploded .war, you also need to add this file.)

$vi WEB-INF/jboss-web.xml$ cat WEB-INF/jboss-web.xml
<!DOCTYPE jboss-web PUBLIC
"-//JBoss//DTD Web Application 5.0//EN"
"http://www.jboss.org/j2ee/dtd/jboss-web_5_0.dtd">
<jboss-web>
</jboss-web>

Repack the .war file that you can then deploy.

$jar -cf ../openam.war * Before you deploy OpenAM, update these JVM options. -server Use -server rather than -client. -XX:MaxPermSize=256m Set the permanent generation size to 256 MB. -Xmx1024m Make sure OpenAM has at least 1 GB heap. ## 1.7. Preparing OpenAM & JBoss 7 JBoss 7 requires some preparation prior to deploying OpenAM. The following instructions provide guidance for both standalone and domain deployments. OpenAM must be able to store its configuration between restarts. Procedure 1.1. Preparing JBoss 7 1. Stop JBoss. 2. Add the Sun x509 security module path to the JBoss 7 configuration (sun/security/x509). The following example uses JBoss 7.1.1. $ vi /path/to/jboss7/modules/sun/jdk/main/module.xml
<path name="com/sun/security/auth"/>
<path name="com/sun/security/auth/module"/>
+ <path name ="sun/security/x509"/>
3. Disable modules that conflict with OpenAM REST libraries. All jaxrs references need to be removed from the configuration.

### Note

For JBoss 7.1.0 Final, in addition to removing the following references, remove all org.jboss.as.webservices references. You will need to remove the extension and all related subsystem tags.

• The following example uses JBoss 7.1.1 standalone. Remember to remove all subsystems and extension tags associated with urn:jboss:domain:jaxrs:1.0.

$vi /path/to/jboss7/standalone/configuration/standalone.xml <extension module="org.jboss.as.ejb3"/> - <extension module="org.jboss.as.jaxrs"/> .... - <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/> <subsystem xmlns="urn:jboss:domain:jca:1.1"> • The following example uses JBoss 7.1.1 for a managed domain. $ cp /path/to/jboss7/domain/configuration/
$vi domain.xml <extension module="org.jboss.as.ejb3"/> - <extension module="org.jboss.as.jaxrs"/> .... - <subsystem xmlns="urn:jboss:domain:jaxrs:1.0"/> <subsystem xmlns="urn:jboss:domain:jca:1.1"> 4. Update the openam.war before deploying OpenAM. JBoss will deploy applications from different temporary directories every time you restart the server, forcing you to reconfigure OpenAM. Updating or expanding the openam.war will anchor the configuration. 1. Create a temporary directory and expand the openam.war. $ cd /temp
$mkdir openamtemp ; cd openamtemp$ jar xvf ~/Downloads/openam-server-10.2.0-SNAPSHOT.war
2. Update the # configuration.dir= line in the bootstrap.properties file so that it appears as follows, and save the change.

$vi WEB-INF/classes/bootstrap.properties # This property should also be used when the system user that # is running the web/application server process does not have # a home directory. i.e. System.getProperty("user.home") returns # null. configuration.dir=$HOME/openamJboss
3. Rebuild the openam.war file.

$java -server -Xmx1024m -XX:MaxPermSize=256m -jar start.jar ## 1.9. Preparing Oracle WebLogic Before you deploy OpenAM, update these JVM options. -server Use -server rather than -client. -XX:MaxPermSize=256m Set the permanent generation size to 256 MB. -Xmx1024m Make sure OpenAM has at least 1 GB heap. ## 1.10. Preparing IBM® WebSphere® Before you deploy OpenAM, add these JVM parameters in the Administrator console. Generic JVM arguments -DamCryptoDescriptor.provider=IBMJCE -DamKeyGenDescriptor.provider=IBMJCE Make sure OpenAM has at least 1 GB heap. ## Chapter 2. Installing OpenAM Core Services This chapter covers tasks required for a full install of OpenAM core services including the OpenAM console and installation of only the core services. To manage access to resources on other servers, you can use either OpenIG or one of the OpenAM policy agents. OpenIG is a high-performance reverse proxy server with specialized session management and credential replay functionality. It can function as a standards-based policy enforcement point. Policy agents provide policy enforcement on supported web servers and Java EE containers, and are tightly integrated with OpenAM. See the Policy Agent Installation Guide for instructions on installing OpenAM agents in supported web servers and Java EE application containers. The openam.war file contains all OpenAM server components and samples. How you deploy the .war file depends on your web application container. Select the .war file based on the type of deployment you need, as defined in the following table. Table 2.2. Determine Which War File to Deploy If you want to...Use... Install core OpenAM and the consoleopenam-server-10.2.0-SNAPSHOT.war Install OpenAM with distributed authenticationopenam-distauth-10.2.0-SNAPSHOT.war Install OpenAM with no consoleopenam-server-only-10.2.0-SNAPSHOT.war Procedure 2.1. To Deploy OpenAM 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.

Procedure 2.2. To Configure OpenAM With Defaults (For Evaluation)

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.

### Note

The configuration settings are saved to the $HOME of the user running the web application container. If you would like the configuration files stored somewhere else, such as /opt/openam, you will need to run the Custom Configuration. 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 OpenAM administrator with the first of the two passwords you provided. Procedure 2.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:
/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 Procedure 2.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. 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 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. 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. 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. 8. When the configuration completes, click Proceed to Login, and then login as OpenAM administrator. 9. Restrict permissions to the configuration directory (by default $HOME/openam, where $HOME corresponds to the user who runs the web container). Procedure 2.5. Configuring an Additional Instance 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. 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. 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. 6. Verify the Configurator Summary Details. 7. When the configuration completes, click Proceed to Login, and then login as OpenAM administrator. Now when an end user logs into a server on a load balancer, they will have a persistent session, even if the first server the user logs into fails. Procedure 2.6. To Deploy the Core Services On Tomcat 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.

## Chapter 3. Installing OpenAM Tools

OpenAM tools are found in three .zip files where you unpacked the archive of the entire package, such as ~/Downloads/openam.

openam-distribution-ssoadmintools-10.2.0-SNAPSHOT.zip

openam-distribution-ssoconfiguratortools-10.2.0-SNAPSHOT.zip

Tool to check for command line installation, upgrade, and initial configuration, as well as serving as a command line alternative to using the GUI configuration wizard

openam-distribution-diagnostics-10.2.0-SNAPSHOT.zip

Tool to check for problems with your deployment and configuration

Procedure 3.1. To Set Up Administration Tools
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/
...
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. Procedure 3.2. To Set Up Configuration Tools 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.

Procedure 3.3. To Set Up Diagnostic Tool

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.

## 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. Deploy the openam-distauth-10.2.0-SNAPSHOT.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.

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

Firewall configuration is not described here.

Procedure 4.1. To Deploy the DAS on Tomcat
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.

Procedure 4.2. To Configure the DAS
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.

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 ## Chapter 5. 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. ### Tip 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 ~/Downloads/openam into a staging directory, apply your changes in the staging directory, and use the jar command to prepare the deployable .war. Procedure 5.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 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.

Procedure 5.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/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 Procedure 5.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. ## 5.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=openam,dc=forgerock,dc=org, therefore, the relative distinguished name attribute 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. Realm 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. suffix_client-locale-language_client-locale-territory/services/realm/client-name/file-name Example 5.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. openam_en_GB/services/realm/html/Login.jsp openam_en_GB/services/realm/Login.jsp openam_en_GB/services/html/Login.jsp openam_en_GB/services/Login.jsp openam_en_GB/html/Login.jsp openam_en_GB/Login.jsp openam_en/services/realm/html/Login.jsp openam_en/services/realm/Login.jsp openam_en/services/html/Login.jsp openam_en/services/Login.jsp openam_en/html/Login.jsp openam_en/Login.jsp openam_hu_HU/services/realm/html/Login.jsp openam_hu_HU/services/realm/Login.jsp openam_hu_HU/services/html/Login.jsp openam_hu_HU/services/Login.jsp openam_hu_HU/html/Login.jsp openam_hu_HU/Login.jsp openam_hu/services/realm/html/Login.jsp openam_hu/services/realm/Login.jsp openam_hu/services/html/Login.jsp openam_hu/services/Login.jsp openam_hu/html/Login.jsp openam_hu/Login.jsp openam/services/realm/html/Login.jsp openam/services/realm/Login.jsp openam/services/html/Login.jsp openam/services/Login.jsp openam/html/Login.jsp openam/Login.jsp default_en_GB/services/realm/html/Login.jsp default_en_GB/services/realm/Login.jsp default_en_GB/services/html/Login.jsp default_en_GB/services/Login.jsp default_en_GB/html/Login.jsp default_en_GB/Login.jsp default_en/services/realm/html/Login.jsp default_en/services/realm/Login.jsp default_en/services/html/Login.jsp default_en/services/Login.jsp default_en/html/Login.jsp default_en/Login.jsp default_hu_HU/services/realm/html/Login.jsp default_hu_HU/services/realm/Login.jsp default_hu_HU/services/html/Login.jsp default_hu_HU/services/Login.jsp default_hu_HU/html/Login.jsp default_hu_HU/Login.jsp default_hu/services/realm/html/Login.jsp default_hu/services/realm/Login.jsp default_hu/services/html/Login.jsp default_hu/services/Login.jsp default_hu/html/Login.jsp default_hu/Login.jsp default/services/realm/html/Login.jsp default/services/realm/Login.jsp default/services/html/Login.jsp default/services/Login.jsp default/html/Login.jsp default/Login.jsp ## Chapter 6. Setting Up OpenAM Session Failover This chapter covers setting up session failover (SFO) 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. SFO 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. Configuring an Additional Instance provides the steps to configure each instance of OpenAM. The following procedure describes how to configure an OpenAM server to use a load balancer for the first instance if it was not part of the initial configuration. ### Note Following an upgrade to OpenAM 10.1.0 XPress release, all users will need to login again because OpenAM no longer uses Open Message Queue or Berkeley DB Java Edition for SFO. ### Note SFO is supported within a site or data center with a shared local area network. SFO is not supported across sites and data centers linked by wide area networks (WAN). Procedure 6.1. Configure First OpenAM Instance Behind a Load Balancer 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. Procedure 6.2. Setting a Load Balancer on Existing Configurations 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. Procedure 6.3. Configuring Session Failover after Installation 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. ## Chapter 7. 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 7.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:
/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

## Index

### C

Custom end user pages, Customizing the OpenAM End User Pages

### I

Installing
Behind the firewall, Installing OpenAM Distributed Authentication
Full install, Installing OpenAM Core Services
Interactive configuration, Installing OpenAM Core Services
Load Balancer, Setting Up OpenAM Session Failover
No console, Installing OpenAM Core Services
Session failover, Setting Up OpenAM Session Failover
Silent configuration, Installing OpenAM Tools
Starting over, Installing OpenAM Core Services
Tools (ssoadm, etc.), Installing OpenAM Tools

### M

Memory requirements, Preparing Prerequisite Software

### P

Prerequisites, Preparing For Installation

### S

Software requirements, Preparing Prerequisite Software

### U

Uninstalling, Removing OpenAM Software