Step 1. Prepare your server
To install AM in a demo or test environment, perform the following prerequisite tasks:
- Check disk space
.warfile includes an embedded DS server, which stores AM’s configuration data and serves as an identity store.
The DS server requires free disk space equal to or greater than 5 GB, plus 5% of the total size of the filesystem in the $HOME directory of the user running the container.
- Prepare a fully qualified domain name (FQDN)
AM requires that you use fully qualified domain names. This is because AM uses HTTP cookies to keep track of sessions for single sign-on (SSO), and setting and reading cookies depends on the server name and domain.
For information on preparing an FQDN, see Prepare a fully qualified domain name.
- Install a supported Java development kit (JDK)
AM is a Java web application, so you need to download and install a supported JDK. For a list of JDK versions that AM supports, see Java requirements.
For information on installing a JDK, see Install a JDK and Apache Tomcat.
Ensure that the JDK’s default truststore, for example,
$JAVA_HOME/lib/security/cacerts, has, at least,
$ sudo chmod 644 $JAVA_HOME/lib/security/cacerts
Why is this required?
When evaluating AM, the installation process deploys an embedded DS instance that AM uses as configuration store, user store, and CTS store. To connect to the DS instance using LDAPS, AM requires access to the self-signed certificate that DS generates.
If you are installing AM for evaluation purposes, AM creates a copy of your JDK’s default
lib/security/cacertstruststore, names it
truststore, and places it in
AM then attempts to add the DS self-signed certificate to that store, with an alias of
lib/security/cacertstruststore does not have the default password of
changeit, and/or if it does not have at least
644permissions, then AM installation will fail, as it will not be able to open the truststore to add the DS certificate.
You can change the permissions back as they were originally after installing AM.
- Install a supported web container
Although AM can run in a number of application servers, download Apache Tomcat for now.
For a list of versions that AM supports, see Web application container requirements.
For information on installing Apache Tomcat, see Install a JDK and Apache Tomcat.
- Download ForgeRock Access Management
The ForgeRock BackStage download site hosts downloadable versions of AM.
For a list of supported operating systems, see Operating system requirements.
The procedures to set up the software are written for use on a UNIX-like system.
If you are running Microsoft Windows, adapt these examples accordingly.
Before deploying and installing AM, give your system a DNS alias, such as
You can add a DNS alias by editing your hosts file.
If you already have a DNS server set up, or use a service such as localtest.me, you can use those instead of editing your hosts file.
Add the aliases to your hosts file using your preferred text editor:
# Edit /etc/hosts $ sudo vi /etc/hosts Password: $ cat /etc/hosts | grep openam 127.0.0.1 localhost openam.example.com
Proceed to install a JDK and Apache Tomcat.
AM runs as a Java web application inside an application container.
Apache Tomcat is an application container that runs on a variety of platforms.
The following instructions are loosely based on the
RUNNING.txt file delivered with Apache Tomcat:
Extract the JDK download file:
$ mkdir -p /path/to/JDK $ unzip ~/Downloads/openjdk-X_bin.zip -d /path/to/JDK
Extract the Apache Tomcat download file:
$ mkdir -p /path/to/tomcat $ unzip ~/Downloads/apache-tomcat-X.X.XX.zip -d /path/to/tomcat
Create an Apache Tomcat script to set the
JAVA_HOMEenvironment variable to the file system location of the JDK and to set the heap and metaspace size appropriately. For example:
export JAVA_HOME="/path/to/usr/jdk" export CATALINA_OPTS="$CATALINA_OPTS -Xmx2g -XX:MaxMetaspaceSize=256m"
PS C:\path\to> $env:JAVA_HOME += ";C:\path\to\usr\jdk" PS C:\path\to> $env:CATALINA_OPTS += ";-Xmx2g -XX:MaxMetaspaceSize=256m"
(UNIX-like systems only) Make the scripts in Apache Tomcat’s
$ chmod +x /path/to/tomcat/bin/*.sh
If you have a custom installation that differs from the documented Apache Tomcat installation, make sure to set Apache Tomcat’s
CATALINA_TMPDIRto a writable directory to ensure the installation succeeds. This temporary directory is used by the JVM (
java.io.tmpdir) to write disk-based storage policies and other temporary files.
Make sure that your system’s firewall does not block the port that Apache Tomcat uses (
See the Apache documentation for instructions for allowing traffic through the firewall on a specific port for the version of Apache Tomcat on your system. A variety of firewalls are in use on Linux systems. The version your system uses depends on your specific distribution.
Start Apache Tomcat:
It might take Apache Tomcat several seconds to start. When it has successfully started, you should see information indicating how long startup took in the
INFO: Server startup in 4655 ms
Go to Apache Tomcat’s homepage; for example,
If Apache Tomcat works correctly, the homepage displays a success message: "If you’re seeing this, you’ve successfully installed Tomcat. Congratulations!".
Proceed to Step 2. Deploy AM.