Step 1. Prepare Your Server

To install AM in a demo or test environment, you need to perform the following prerequisite tasks:

Check Disk Space

AM's distribution .war file 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 "To 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, refer to Java.

For information on installing a JDK, see "To Install a JDK and Apache Tomcat".

Important

Ensure that the JDK's default truststore, for example, $JAVA_HOME/lib/security/cacerts, has, at least, 644 permissions:

$ 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/cacerts truststore, names it truststore, and places it in /path/to/openam/security/keystores/.

AM then attempts to add the DS self-signed certificate to that store, with an alias of ds-ca-cert.

Important

If the lib/security/cacerts truststore does not have the default password of changeit, and/or if it does not have at least 644 permissions, 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 the purposes of this guide.

For a list of versions that AM supports, see Application containers.

For information on installing Apache Tomcat, see "To 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, refer to Operating systems.

Note

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.

To Prepare a Fully Qualified Domain Name

Before deploying and installing AM, give your system a DNS alias, such as openam.example.com. You can add a DNS alias by editing your hosts file.

Tip

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:

$ sudo vi /etc/hosts
Password:

### Edit /etc/hosts ###

$ cat /etc/hosts | grep openam
127.0.0.1    localhost openam.example.com

Proceed to install a JDK and Apache Tomcat.

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

(UNIX-like systems only) Make the scripts in Apache Tomcat's bin/ directory executable:
```
$ chmod +x /path/to/tomcat/bin/*.sh
```
Create an Apache Tomcat setenv.sh (Unix/Linux) or setenv.bat (Windows) script to set the JAVA_HOME environment variable to the file system location of the JDK, and to set the heap and metaspace size appropriately:
```
export JAVA_HOME="/path/to/usr/jdk"
export CATALINA_OPTS="$CATALINA_OPTS -Xmx2g -XX:MaxMetaspaceSize=256m"
```
(Optional) If you have a custom installation that differs from the documented Apache Tomcat installation, make sure to set Apache Tomcat's CATALINA_TMPDIR to 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 (8080 by default).
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:
```
$ /path/to/tomcat/bin/startup.sh
```
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 /path/to/tomcat/logs/catalina.out log file.
```
INFO: Server startup in 4655 ms
```
Navigate to Apache Tomcat's home page; for example, http://openam.example.com:8080.
If Apache Tomcat works correctly, the "If you're seeing this, you've successfully installed Tomcat. Congratulations!" page appears.
Proceed to Step 2. Deploy AM.