How do I build OpenAM 13.x from source?

Last updated Jan 5, 2021

The purpose of this article is to provide guidance on building OpenAM Enterprise and Maintenance releases from source. This method uses ForgeRock password protected Apache Maven™ repositories, which include the required artifacts. Artifacts for releases are only available when using these repositories; release builds will fail without these artifacts.

5 readers recommend this article

Archived

This article has been archived and is no longer maintained by ForgeRock.

Warning

ForgeRock support covers the use of the official binary builds made available and downloaded from our customer portal: BackStage. We will support builds made from source providing no changes have been made to the core code of the product, the product was built from a tag that matches an official release, for example, 13 and said product was built using the ForgeRock build scripts provided as part of the source. In the event that a customer experiences an issue with a ForgeRock product built from source where ForgeRock believe the issue is as a result of the build process, ForgeRock reserves the right to ask the customer to attempt to reproduce the issue on an official ForgeRock binary build. Customers who are running custom builds or who need further clarification should contact their ForgeRock sales representative.

Overview

The OpenAM source code is available in Git repositories hosted on our Bitbucket® Server.

You should follow this process to build OpenAM successfully:

Generate a ~/.m2/settings.xml file per How do I access the ForgeRock protected Maven repositories? It is essential that you create a valid settings.xml to access the Maven repositories needed for the build process. Failing to do this will cause your build to fail.
Install the correct versions of Oracle® JDK and Apache Maven™ as detailed in the Dependencies section.
Create a SSH key and add it to your Bitbucket profile to allow you to clone the source code with a SSH URL.
Set up the OpenDMK library as detailed in How do I set up the OpenDMK library for building AM or DS from source?
Build OpenAM using the steps in one of the following sections only depending on what you are trying to build:
Read the Troubleshooting section if you encounter any issues as this covers the common issues that can cause a build to fail.

* The SecurID authentication module is missing in OpenAM 13.0; you can either follow the steps in this article to include it when you build from source or can apply a patch to your WAR file as detailed in SecurID authentication module is missing from OpenAM 13.0.

Note

You may notice that one of the artifacts is downloaded from an Oracle® repository (http://download.oracle.com/maven); this is the database engine (Berkeley DB Java Edition) which does come from the Oracle library. As of AM 5 / DS 5, we use a new JE version (7.3), which is Apache V2 and Open Source; this newer version is hosted in the ForgeRock repository.

Dependencies

You should use Git 1.7.6 or above, and build with the appropriate version of Oracle JDK and Maven depending on your version of OpenAM:

Version	Oracle JDK version	Maven version
OpenAM 13.5.x	1.7 *	3.3.0 or later
OpenAM 13.0.0	1.7 or 1.8	3.1.0 or later

* There is a known issue with building OpenAM 13.5.x with JDK 1.8: OPENAM-10314 (OpenAM Maven Javadocs does not work with Java 8.).

Enterprise release

You can build an Enterprise release from source as follows:

Git clone the OpenAM enterprise releases repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/openam-public.git
Find the required tag in the repository you just cloned; the git tag command lists all the tags in a repository: $ cd openam-public $ git tag 10.1.0-Xpress 11.0.0 12.0.0 12.0.0-1 13.0.0
Check out the required tag. For example, 13.0.0: $ git checkout 13.0.0
Set your Maven options: $ export MAVEN_OPTS=-Xmx512m
Build OpenAM using the following command: $ mvn clean install If all is successful, you'll find that everything has been built in ./openam-server/target.

Maintenance release

You can build a Maintenance release from source as follows:

Git clone the OpenAM maintenance releases repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/openam-sustaining-external.git
Find the required tag in the repository you just cloned; the git tag command lists all the tags in a repository: $ cd openam-sustaining-external $ git tag 10.1.0-Xpress 10.1.0-Xpress-docs 11.0.0 12.0.0 12.0.0-1 12.0.0-2 12.0.0-3 13.0.0 13.5.0 ....
Check out the required tag. For example, 13.5.0: $ git checkout 13.5.0
Set your Maven options: $ export MAVEN_OPTS=-Xmx512m
Build OpenAM using the following command: $ mvn clean install If all is successful, you'll find that everything has been built in ./openam-server/target.

Enterprise release with SecurID authentication module

You can build an Enterprise release with the SecurID authentication module from source as follows:

Request the latest authapi jar file from RSA®.
Install the authapi jar file using the following command (replacing 2005-08-12 with the version of the jar file provided by RSA): $ mvn install:install-file -Dfile=./authapi-2005-08-12.jar -DgroupId=external -DartifactId=authapi -Dversion=2005-08-12 -Dpackaging=jar
Git clone the OpenAM enterprise releases repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/openam-public.git
Find the required tag in the repository you just cloned; the git tag command lists all the tags in a repository: $ cd openam-public $ git tag 10.1.0-Xpress 11.0.0 12.0.0 12.0.0-1 13.0.0
Check out the required tag. For example, 13.0.0: $ git checkout 13.0.0
Set your Maven options: $ export MAVEN_OPTS=-Xmx512m
Update the openam-authentication/openam-auth-securid/pom.xml file in the checked out source to correct the OpenAM version. This shows as follows: <version>13.0.0-SNAPSHOT</version> And should be changed to: <version>13.0.0</version>
Build OpenAM using the following command: $ mvn clean install -Prelease If all is successful, you'll find that everything has been built in ./openam-server/target.
Run the following ssoadm command to update the service schema with the SecurID authentication module: $ ./ssoadm update-svc [adminID] -f [passwordfile] -X amAuthSecurID.xml replacing [adminID] and [passwordfile] with appropriate values.

Maintenance release with SecurID authentication module

You can build a Maintenance release with the SecurID authentication module from source as follows:

Request the latest authapi jar file from RSA.
Install the authapi jar file using the following command (replacing 2005-08-12 with the version of the jar file provided by RSA): $ mvn install:install-file -Dfile=./authapi-2005-08-12.jar -DgroupId=external -DartifactId=authapi -Dversion=2005-08-12 -Dpackaging=jar
Git clone the OpenAM maintenance releases repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/openam-sustaining-external.git
Find the required tag in the repository you just cloned; the git tag command lists all the tags in a repository: $ cd openam-sustaining-external $ git tag 10.1.0-Xpress 10.1.0-Xpress-docs 11.0.0 12.0.0 12.0.0-1 12.0.0-2 12.0.0-3 13.0.0 13.5.0 ....
Check out the required tag. For example, 13.5.0: $ git checkout 13.5.0
Set your Maven options: $ export MAVEN_OPTS=-Xmx512m
Build OpenAM using the following command: $ mvn clean install -Prelease If all is successful, you'll find that everything has been built in ./openam-server/target.

Troubleshooting

If your build fails, you should check the following:

Verify you are using an up-to-date ~/.m2/settings.xml file. If you are not sure, you should regenerate it per How do I access the ForgeRock protected Maven repositories? and copy it to the ~/.m2 directory.
The JAVA_HOME variable has been set correctly. You can check it using the following command: $ echo $JAVA_HOME
You are using an appropriate version of Maven and Oracle JDK. You can check this using the following command: $ mvn --version
You have set up the OpenDMK library per How do I set up the OpenDMK library for building AM or DS from source?.
If all the above is correct and your build still fails, it is likely that network issues are to blame, for example, you have a firewall that is preventing the build from calling out to the repository.