Access Management 7.3.1

Step 1. Prepare your server

To install AM in a demo or test environment, 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 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 the list of supported JDK versions, refer to the 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, 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.

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 now.

For the list of supported versions, refer to Application containers.

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 the list of supported operating systems, refer to the 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.

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.

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.

  1. 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

  2. Proceed to install a JDK and Apache Tomcat.

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:

  1. Extract the JDK download file:

    $ mkdir -p /path/to/JDK
$ unzip ~/Downloads/openjdk-X_bin.zip -d /path/to/JDK

  2. Extract the Apache Tomcat download file:

    $ mkdir -p /path/to/tomcat
$ unzip ~/Downloads/apache-tomcat-X.X.XX.zip -d /path/to/tomcat

  3. Create an Apache Tomcat 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. For example:

    • Unix/Linux

    • Windows

    Create a setenv.sh script in /path/to/tomcat/bin/:

    export JAVA_HOME="/path/to/usr/jdk"
export CATALINA_OPTS="$CATALINA_OPTS -Xmx2g -XX:MaxMetaspaceSize=256m"

    Create a setenv.bat script in \path\to\tomcat\bin\:

    PS C:\path\to> $env:JAVA_HOME += ";C:\path\to\usr\jdk"
PS C:\path\to> $env:CATALINA_OPTS += ";-Xmx2g -XX:MaxMetaspaceSize=256m"

  4. (UNIX-like systems only) Make the scripts in Apache Tomcat’s bin/ directory executable:

    $ chmod +x /path/to/tomcat/bin/*.sh

  5. 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.

  6. 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.

  7. 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

  8. Go to Apache Tomcat’s homepage; for example, http://openam.example.com:8080.

    If Apache Tomcat works correctly, the homepage displays a success message: "If you’re seeing this, you’ve successfully installed Tomcat. Congratulations!".

  9. Proceed to Step 2. Deploy AM.