This chapter covers tasks required for a full install of OpenAM server with or without OpenAM Console.
This chapter does not cover installation for enforcing policies on resource servers. To manage access to resources on other servers, you can use OpenIG or 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.
OpenAM policy agents provide policy enforcement on supported web servers and Java EE containers, and are tightly integrated with OpenAM. See the OpenAM Web Policy Agent Installation Guide, or OpenAM Java EE Policy Agent Installation Guide for instructions on installing OpenAM policy agents in supported web servers and Java EE application containers.
|If you want to...||Then see...|
|Install quickly for evaluation using default settings||
Alternatively, follow the full example in the Getting Started guide.
|Install OpenAM server and console, choosing settings||Procedure 2.1, “To Deploy OpenAM” and Procedure 2.4, “To Configure OpenAM”|
|Erase the configuration and start over||Procedure 2.3, “To Delete an OpenAM Configuration Before Redeploying”|
|Add an OpenAM server to a site||Procedure 2.1, “To Deploy OpenAM”, and Procedure 2.5, “To Add a Server to a Site”|
|Install OpenAM server only (no console)||Table 2.2, “Determine Which War File to Deploy”, Procedure 2.1, “To Deploy OpenAM”, and Procedure 2.6, “To Deploy OpenAM Core Server (No Console)”|
|Install ssoadm for CLI configuration||Installing OpenAM Tools, or OpenAM ssoadm.jsp in the Administration Guide|
|Perform a command-line install||To Set Up Configuration Tools|
|Install OpenAM in your DMZ||Installing OpenAM Distributed Authentication|
|Skin OpenAM for your organization||Customizing the OpenAM End User Pages|
|Uninstall OpenAM||Removing OpenAM Software|
.war file based on the type of
deployment you need, as defined in the following table.
|If you want to...||Use...|
|Install an OpenAM server including OpenAM Console|
|Install OpenAM server without OpenAM Console|
|Install OpenAM distributed authentication UI|
OpenAM-12.0.0-SNAPSHOT.war file contains OpenAM
server with OpenAM Console. How you deploy the .war file depends on your web
Deploy the .war file on your container.
For example, copy the file to deploy on Apache Tomcat.
$ cp OpenAM-12.0.0-SNAPSHOT.war /path/to/tomcat/webapps/openam.war
You change the file name to
deploying in Tomcat so that the deployment URI is
In order to be properly configured, OpenAM requires a deployment URI
with a non-empty string after
Do not deploy OpenAM at the root context.
Do not rename the .war file to
before deploying on Tomcat, for example.
It can take several seconds for OpenAM to be deployed in your container.
Browse to the initial configuration screen, for example at
The default configuration option configures the embedded OpenDJ server using default ports—if the ports are already in use, OpenAM uses free ports—as both configuration store and identity store.
The default configuration sets the cookie domain based on the fully
qualified domain name of the system. For an FQDN
openam.example.com, the cookie domain is set to
Configuration settings are saved to the home directory of the user
running the web application container in a directory named after the
deployment URI. In other words if OpenAM is deployed under
/openam, then the configuration is saved under
In the initial configuration screen, click Create Default Configuration under Default Configuration.
Provide different passwords for the default OpenAM administrator,
amadmin, and default Policy Agent users.
When the configuration completes, click Proceed to Login, and then login as the OpenAM administrator with the first of the two passwords you provided.
After successful login, OpenAM redirects you to OpenAM Console.
If you are unhappy with your configuration and want to start over from the beginning, follow these steps.
Stop the OpenAM web application to clear the configuration held in memory.
The following example shuts down Tomcat for example.
$ /path/to/tomcat/bin/shutdown.sh Password: Using CATALINA_BASE: /path/to/tomcat Using CATALINA_HOME: /path/to/tomcat Using CATALINA_TMPDIR: /path/to/tomcat/temp Using JRE_HOME: /path/to/jdk/jre Using CLASSPATH: /path/to/tomcat/bin/bootstrap.jar:/path/to/tomcat/bin/tomcat-juli.jar
Delete OpenAM configuration files, by default under the
$HOME of the user running the web application
$ rm -rf $HOME/openam $HOME/.openamcfg
When using the internal OpenAM configuration store, this step deletes the embedded directory server and all of its contents. This is why you stop the application server before removing the configuration.
If you use an external configuration store, also delete the entries under the configured OpenAM suffix (by default dc=openam,dc=forgerock,dc=org).
Restart the OpenAM web application.
The following example starts the Tomcat container.
$ /path/to/tomcat/bin/startup.sh Password: Using CATALINA_BASE: /path/to/tomcat Using CATALINA_HOME: /path/to/tomcat Using CATALINA_TMPDIR: /path/to/tomcat/temp Using JRE_HOME: /path/to/jdk/jre Using CLASSPATH: /path/to/tomcat/bin/bootstrap.jar:/path/to/tomcat/bin/tomcat-juli.jar
In the initial configuration screen, click Create New Configuration under Custom Configuration.
Provide a password having at least 8 characters for the OpenAM
Make sure the server settings are valid for your configuration.
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
/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
Starts with a dot (
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).
Location on server for OpenAM configuration files. OpenAM must be able to write to this directory.
In the Configuration Store screen, you can accept the defaults to allow OpenAM to store configuration data in an embedded directory. The embedded directory can be configured separately to replicate data for high availability if necessary.
You can also add this OpenAM installation to an existing deployment, providing the URL of the site. See Procedure 2.5, “To Add a Server to a Site” for details.
Alternatively, if you already manage an OpenDJ or DSEE deployment, you can choose to store OpenAM configuration data in your existing directory service. You must, however, create the suffix to store configuration data on the directory server before you configure OpenAM. OpenAM does not create the suffix when you use an external configuration store.
When you create a new OpenAM custom configuration that uses an
external LDAP directory server for the configuration data store, you must
use a root suffix DN with at least two domain components, such as
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.
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.
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.
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.
Base distinguished name (DN) where user data are stored
Directory administrator user DN. The administrator must be capable of updating schema and user data.
Password for the directory administrator user
In the Site Configuration screen, you can set up OpenAM as part of a site where the load is balanced across multiple OpenAM servers.
If you have a site configuration with a load balancer, you can enable session high availability persistence and failover. OpenAM then stores sessions across server restarts, so that users do not have to login again.
If you then add additional servers to this OpenAM site, OpenAM performs session failover, storing session data in a directory service that is shared by different OpenAM servers. The shared storage means that if an OpenAM server fails, other OpenAM servers in the site have access to the user's session data and can serve requests about that user. As a result the user does not have to log in again. If session failover is important for your deployment, also follow the instructions in Setting Up OpenAM Session Failover.
It is possible to set up a site after initial installation and configuration. Doing so is described in the chapter on Setting Up OpenAM Session Failover.
In the Agent Information screen, provide a password having at least 8 characters to be used by policy agents to connect to OpenAM.
Check the summary screen, and if necessary click Previous to return to earlier screens if necessary to fix configuration errors.
After you click Create Configuration in the summary screen, configuration proceeds, logging progress that you can read in your browser and later in the installation log. The process ends, and OpenAM shows the Proceed to Login prompt.
When the configuration completes, click Proceed to Login, and then
login as the OpenAM administrator,
After login, OpenAM redirects you to the OpenAM Console page.
You can also access OpenAM Console by browsing to the Console URL, such
Restrict permissions to the configuration directory (by default
$HOME corresponds to the user who runs the web container). Prevent other
users from accessing files in the configuration directory.
High availability requires redundant servers in case of failure. With OpenAM, you configure an OpenAM site with multiple servers in a pool behind a load balancing service the exposes a single URL as an entry point to the site.
Follow these steps to configure a server to belong to an existing site.
In the initial configuration screen, under Custom Configuration click Create New Configuration.
In the first screen, enter the same password entered for the OpenAM
amadmin, when you configured the first
server in the site.
Configure server settings as required.
The cookie domain should be identical to that of the first server in the site.
In the configuration store screen, select Add to Existing Deployment, and enter as the Server URL the URL of the first OpenAM server in the site.
The directory used to store configuration data should belong to the same directory service used for this purpose by other OpenAM servers in the site. If you use the embedded OpenDJ directory server, for example, you can have the configurator set up data replication with embedded directory servers used by other servers in the site.
Settings for the user store are then shared with the existing server, so the corresponding wizard screen is skipped.
In the site configuration screen, select
enter the same site configuration details as you did for the first server
in the site.
Settings for agent information are also shared with the existing server, so the corresponding wizard screen is skipped.
In the summary screen, verify the settings you chose, and then click Create Configuration.
When the configuration process finishes, click Proceed to Login, and then login as the OpenAM administrator to access OpenAM Console.
You can deploy OpenAM server without OpenAM console by performing the following steps.
in your container.
For example, copy the file to deploy on Apache Tomcat.
$ cp OpenAM-ServerOnly-12.0.0-SNAPSHOT.war /path/to/tomcat/webapps/coreonly.war
Browse to the configuration application, such as
http://openam.example.com:8080/coreonly/, and configure
OpenAM core services as in Procedure 2.4, “To Configure OpenAM”.
After configuration, restrict permissions to the configuration
directory, such as
$HOME corresponds to the user who runs the web
container. Prevent other users from accessing files in the configuration