How To
Archived

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:

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

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:

  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)


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.