How do I build OpenAM 13.x from source?

Overview

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

You should follow this process to build OpenAM successfully:

1. 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.
2. Install the correct versions of Oracle® JDK and Apache Maven™ as detailed in the Dependencies section.
3. Create a SSH key and add it to your Bitbucket profile to allow you to clone the source code with a SSH URL.
4. Set up the OpenDMK library as detailed in How do I set up the OpenDMK library for building AM or DS from source?
5. Build OpenAM using the steps in one of the following sections only depending on what you are trying to build:
   • Enterprise release
   • Maintenance release
   • Enterprise release with SecurID® authentication module *
   • Maintenance release with SecurID authentication module *
6. 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.

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:

* 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:

1. Git clone the OpenAM enterprise releases repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/openam-public.git
2. 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
3. Check out the required tag. For example, 13.0.0: $ git checkout 13.0.0
4. Set your Maven options: $ export MAVEN_OPTS=-Xmx512m
5. 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:

1. Git clone the OpenAM maintenance releases repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/openam-sustaining-external.git
2. 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 ....
3. Check out the required tag. For example, 13.5.0: $ git checkout 13.5.0
4. Set your Maven options: $ export MAVEN_OPTS=-Xmx512m
5. 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:

1. Request the latest authapi jar file from RSA®.
2. 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
3. Git clone the OpenAM enterprise releases repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/openam-public.git
4. 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
5. Check out the required tag. For example, 13.0.0: $ git checkout 13.0.0
6. Set your Maven options: $ export MAVEN_OPTS=-Xmx512m
7. 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>
8. 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.
9. 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:

1. Request the latest authapi jar file from RSA.
2. 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
3. Git clone the OpenAM maintenance releases repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/openam-sustaining-external.git
4. 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 ....
5. Check out the required tag. For example, 13.5.0: $ git checkout 13.5.0
6. Set your Maven options: $ export MAVEN_OPTS=-Xmx512m​​​​​
7. 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.

See Also

FAQ: Source code in AM

How do I access the ForgeRock protected Maven repositories?

SecurID authentication module is missing from OpenAM 13.0

FAQ: SecurID authentication module in AM

Source code in ForgeRock products

Maven Settings Reference

Related Training

N/A

Related Issue Tracker IDs

OPENAM-10317 (OpenAM 13.5.x openam-ui-ria does not build on Windows and Linux)

OPENAM-10316 (Remove error from Maven build on openam-ui-ria for Windows)

OPENAM-10314 (OpenAM Maven Javadocs does not work with Java 8.)

OPENAM-9707 (compilation of 13.5.0 fails on windows during tests: FileSystemNotFoundException setup%5cinstalled-opendj-base-directory.zip)

OPENAM-9526 (Compiling the source code without git repo fails at openam-clientsdk module)

OPENAM-8456 (SecurID authentication module is missing from 13.0.0)