Source code in ForgeRock products

This book provides information on source code and binaries in ForgeRock products (AM, DS, IDM and IG).


Building from Source


How do I update my custom password storage scheme or server plugin when I upgrade DS (All versions)?

The purpose of this article is to provide assistance if you have a custom password storage scheme or server plugin that you want to migrate to a newer DS version after upgrading DS.

Overview

The following examples are bundled with the DS software to help you extend DS:

  • Server Plugin (example-plugin.zip) - see Customization for further information.
  • Password Storage Scheme (example-pwdscheme.zip) - see DS 6.5 Product Improvements for further information (DS 6.5 and later).

If you have previously created a custom extension based on the above examples, you must update it for compatibility with newer versions of DS when you upgrade. You can do this in one of two ways depending on the level of customizations you have made and the changes in the latest DS version:

  • Rework existing customizations and rebuild. Refer to the following section for further information.
  • Start fresh using the new DS example and apply your local changes to the latest code. Refer to the example readme and Customization for further information.
Note

Creating/migrating custom server plugins and password storage schemes is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.

Rework existing customizations and rebuild

Note

The repositories that hold the source code use internal version numbers. For DS 5, the internal version number is 4.0.0; as of DS 5.5, the internal version numbers match the product version numbers.

You can rework customizations as follows:

  1. Update the pom.xml file (located in either /path/to/ds/opendj-server-example-plugin or /path/to/ds/opendj-server-example- pwdscheme) to use the dependencies associated with the new DS version. You should compare your pom file to the pom file from the new DS example and update your pom file to include any new or changed dependencies. At the very least, you must check and update the following:
    • Change the version number in the following section to reflect the version number of the new DS. For example, it would look like this if you are upgrading to DS 6.5: <parent> <groupId>org.forgerock.opendj</groupId> <artifactId>opendj-parent</artifactId> <version>6.5.0</version> </parent>
    • If you are upgrading from DS 5, you must update the artifactId for the org.forgerock.opendj dependency. Look for the following dependency: <dependency> <groupId>org.forgerock.opendj</groupId> <artifactId>opendj-server-legacy</artifactId> <version>${project.version}</version> </dependency> And change the artifactId to opendj-server. For example, it should now look like this: <dependency> <groupId>org.forgerock.opendj</groupId> <artifactId>opendj-server</artifactId> <version>${project.version}</version> </dependency>
  2. Migrate your server plugin or password storage scheme code to be compatible with the new DS version. The following pointers should help you:
    • Refer to Customization.
    • Refer to the Javadoc for information on the current API.
    • DS has been migrating away from server-specific classes in the org.opends.server.types Java® package to classes in the org.forgerock.opendj.ldap Java package that are shared between the server and the LDAP SDK. These classes may have new names (for example, the DN class was renamed to Dn class) and may also use different methods (which could affect their behavior).
  3. Rebuild your code per the example readme.

See Also

Understanding source code access for ForgeRock products

How do I access the ForgeRock protected Maven repositories?

File Layout

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I update and recompile the iOS authenticator app with custom branding in AM (All versions)?

The purpose of this article is to provide information on updating and recompiling the iOS® authenticator app in AM so that it can be published to the Apple® App Store. Changes include renaming the app and rebranding changes, such as updating the Splashscreen video, updating the app icon and changing default colors.

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

This article explains how to clone the iOS ForgeRock Authenticator app source code and create your own version of the app that you can publish to the Apple App Store. There is also a section that provides links relevant to setting up Push notifications.

High level steps

  1. Create a new iOS App Bundle ID
  2. Obtain Authenticator source, prepare a project and open in Xcode
  3. Launch the App on an iPhone®
  4. Rename the project
  5. Rename the scheme
  6. Update the CocoaPods configuration
  7. Rename the ForgeRock-Authenticator directory
  8. Rename the Entitlements file
  9. Update the Build settings and rebuild
  10. Update the Test Build settings
  11. Update the Splashscreen video
  12. Update App Permission Request dialogs
  13. Update Localizable.strings
  14. Update About.strings
  15. Update the App icon
  16. Update the Default Account icon
  17. Update the Default colors
  18. Publish your App

These steps were completed using Xcode Version 10.0 (10A255).

Note

Before updating the Authenticator app, please make sure Xcode® is installed and up-to-date.

Create a new iOS App Bundle ID

  1. Log in to your paid Apple Developer account (http://developer.apple.com/account).
  2. Select Certificates, Identifiers & Profiles.
  3. Select App IDs (under Identifiers in the menu on the left).
  4. Select the “+” (Add) icon.
  5. Complete the Registering an App ID form:
    1. Enter an App ID description, for example “ACME Authenticator”.
    2. Select Explicit App ID and enter a bundle ID, for example “com.acme.authenticator”.
    3. Leave default selections for App Services (we will enable “Push Notifications” later in this article):
  1. Select “Register”, then “Done” to complete creation of your new iOS App Bundle ID.

Obtain Authenticator source, prepare a project and open in Xcode

Note

To clone the source code with a SSH URL, you must have created a SSH key and added it to your Bitbucket profile.

  1. Git clone the ForgeRock Authenticator iOS repository: $ git clone ssh://git@stash.forgerock.org:7999/openam/forgerock-authenticator-ios.git
  2. Install CocoaPods. See CocoaPods - Getting Started for further information.
  3. Prepare the project to be opened in Xcode:
    1. Navigate to the project’s root directory on the command line and download the project’s dependencies: $ cd forgerock-authenticator-ios $ pod install 
    2. Open the project in Xcode: $ open ForgeRock.xcworkspace/
  4. Select the “ForgeRock” folder from the “Project Navigator View” in Xcode to view the app’s configuration in the main Xcode view.
  5. Update the App Identity settings:
    1. Bundle identifier, this should be the same as set in step 5b in the previous section, for example “com.acme.authenticator”.
    2. Version, for example “1.0.0”.
    3. Build, for example “1”.
  6. Update the App Signing settings:
    1. Enable “Automatically manage signing”; this is enabled for the official ForgeRock app.
    2. Team, this should refer to your Apple developer account.
    3. Provisioning profile, you should have a provisioning profile.
    4. Signing certificate, you should have a signing certificate.

Before making further changes, now would be a good time to verify that you are able to run the code on a physical device as detailed in Launch the App on an iPhone.

Dependency versions

Downloading the project's dependencies captures the versions in the Podfile.lock file (located in the project's root directory). This ensures that the same versions will be downloaded if the pod install command is re-run.

To update to a newer version of a dependency, you can use a combination of pod outdated to identify dependencies that are outdated and pod update to update them. See CocoaPods install vs update documentation for further details. If you make changes to third-party dependencies, you must also update the LIBRARIES file.

Launch the App on an iPhone

  1. Connect an iPhone to the laptop running Xcode.
  2. Accept the dialog displayed on your iPhone asking if you would like to trust your computer.
  3. Select your phone from the devices dropdown in the top-left of Xcode.
  4. Select the “Play” icon.

Rename the project

  1. Select the “ForgeRock” folder from the “Project Navigator View” in Xcode to view the app’s configuration in the main Xcode view.
  2. Select the "File inspector" on the right hand-side; the name of your project should be in there under "Identity and Type":
  1. Change the name of your project to a new name, for example to “ACME”.
  2. Review the contents that will be renamed by Xcode and select “Rename”:

See How do I completely rename an Xcode project (i.e. inclusive of folders)? for further information on these steps.

Rename the scheme

  1. Click on the scheme for your OLD product (in the top bar near the "Stop" icon), then select "Manage schemes":
  1. Click on the OLD name in the scheme to make it editable and change the name:

See How do I completely rename an Xcode project (i.e. inclusive of folders)? for further information on these steps.

Update the CocoaPods configuration

  1. Close Xcode.
  2. Open the Podfile (located in the project's root directory) in a text editor and update as follows:
    • Rename the target “ForgeRock”, for example to “ACME”.
    • Rename the target “ForgeRockTests”, for example to “ACMETests”:
  1. Navigate to the project’s root directory on the command line and and run the pod install command again to apply the CocoaPods changes: $ cd [project_root_dir] $ pod install
  2. Remove the ForgeRock.xcworkspace directory (also in the project’s root directory): $ rm -rf ForgeRock.xcworkspace
  3. Open the updated project in Xcode: $ open ACME.xcworkspace/

Rename the ForgeRock-Authenticator directory

  1. Close Xcode.
  2. Rename the directory using Git in order to preserve the history: $ git mv ForgeRock-Authenticator ACME-Authenticator
  3. Re-open the project in Xcode: $ open ACME.xcworkspace/
  4. Dismiss any warnings regarding missing files.
  5. Select “Authenticator” from the “Project Navigator View” in Xcode; it should be shown in red.
  6. Navigate to the Utilities pane under "Identity and Type" where you will see the "Name" entry.
  7. Select the folder icon to show a new dialog and update the location:

Rename the Entitlements file

  1. Rename the ForgeRock.entitlements file (located in the project's root directory), for example to ACME.entitlements:

Update the Build settings and rebuild

  1. Select the project from the “Project Navigator View” in Xcode.
  2. Select “General”, scroll down to the “Linked Frameworks and Libraries” section and remove the “libPods-ForgeRock.a” entry:
  1. Select "Build Settings", followed by “Packaging” and update the “Info.plist File” path, for example to “ACME-Authenticator/ACME-Info.plist”:
  1. Navigate to "Signing" and update the following:
    1. “Code Signing Entitlements” path, for example to “ACME.entitlements”.
    2. “Prefix header”, for example to “ACME-Authenticator/ACME-Prefix.pch”:
  1. Rebuild the project:
    1. Command + Shift + K to clean.
    2. Command + B to build.

Before making further changes, now would be a good time to verify that you are able to run the code on a physical device as detailed in Launch the App on an iPhone.

Update the Test Build settings

  1. Select the project from the “Project Navigator View” in Xcode.
  2. Select the “ACMETests” target in the main view.
  3. Select "Build Settings", followed by “Bundle Loader” and update the following:
    1. “Debug” path, for example to “$(BUILT_PRODUCTS_DIR)/ACME.app/ACME”.
    2. “Release” path, for example to “$(BUILT_PRODUCTS_DIR)/ACME.app/ACME”:
  1. Select “Build Phases”, followed by “Link Binary with Libraries” and remove the “libPods-ForgeRockTests.a” entry:

Update the Splashscreen video

  1. Replace the splashvideo.mp4 file (located in the [project_root_dir]/ACME-Authenticator directory) with the updated video file. Keeping the same filename means you do not have to update other project files.

Update App Permission Request dialogs

  1. Replace references to ForgeRock within the ACME-Info.plist file (located in the [project_root_dir]/ACME-Authenticator directory). For example, change them to ACME:

Update Localizable.strings

  1. Replace references to ForgeRock within the Localizable.strings file (located in the [project_root_dir]/ACME-Authenticator/en.lproj directory). For example, change them to ACME:

Update About.strings

  1. Replace relevant references to ForgeRock within the About.strings (located in the [project_root_dir]/ACME-Authenticator/Settings.bundle/en.lproj directory). For example, change them to ACME:
Note

ForgeRock and other copyright attributions should not be changed.

Update the App icon

  1. Generate a new set of icon files and a Contents.json file. These can be generated from a single source image using an online service such as https://appicon.co/.
  2. Replace the contents of the [project_root_dir]/ACME-Authenticator/Images.xcassets/AppIcon.appiconset/ directory with the set of icon files and a Contents.json file:

Update the Default Account icon

  1. Replace the forgerock-logo.png file (located in the [project_root_dir]/ACME-Authenticator directory) with an updated icon. If you want to change the name of this file, for example to acme-logo.png, then you must also update the references to it in the following files (using a text editor to find and replace is likely the easiest approach):
    • FRAUIUtils.m (located in the [project_root_dir]/ACME-Authenticator directory).
    • Main.storyboard (located in the [project_root_dir]/ACME-Authenticator directory)
    • project.pbxproj (located in the [project_root_dir]/ACME.xcodeproj directory):

Optional

You can delete the following files (located in the [project_root_dir]/ACME-Authenticator directory) from Xcode and the file system if you want as they are not used:

  • forgerock-logo-text.png 
  • forgerock-logo-opaque.png 

Update the Default colors

  1. Update colors in the following files (located in the [project_root_dir]/ACME-Authenticator directory); colors to update are specified in brackets:
    • FRANotificationsTableViewController.m (seaGreen and dashboardRed)
    • FRACircleProgressView.m (lightGrey)
    • FRAOathMechanismTableViewCellController.m (seaGreen and dashboardRed)
  2. Update colors and layout defined in the Main.storyboard file (located in the [project_root_dir]/ACME-Authenticator directory) if necessary.
Note

Any changes made to the Main.storyboard file will result in merge conflicts when rebasing over later changes to the official app; ForgeRock's development approach allows edits to this file by only one developer at a time.

Publish your App

Once you have completed all your changes and rebuilt the app, you can submit your app to the Apple App Store. The following links provide useful Apple resources on the next steps:

Set up Push notifications

Refer to the following articles for further information on setting up Push notifications:

See Also

FAQ: Source code in AM

Xcode Help

CocoaPods Guides


Frequently Asked Questions


FAQ: Source code in AM

The purpose of this FAQ is to provide answers to commonly asked questions regarding source code and binaries in AM.

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

Frequently asked questions

Q. How do I access source code to extend AM functionality?

A. The source code to extend AM functionality is available in the am-external repository hosted on our Bitbucket® Server. This code allows you to extend functionality such as the XUI, authentication nodes, authentication modules, the IdRepo, RADIUS code or the Push Notification framework.

See Where can I find source code for AM (All versions)? and Understanding source code access for ForgeRock products for further information.

Q. What credentials do I use to log into Bitbucket?

A. You can log into Bitbucket with your BackStage username and password. Your BackStage username is different to your email address.

Note

You can log into BackStage using either your email address or username, but you must use your username to log into Bitbucket.

You must also be authenticated to access the Maven repositories; see How do I access the ForgeRock protected Maven repositories? for further information. 

Q. How do I access nightly builds and documentation?

A. You can access nightly builds (binaries) and documentation as detailed in How do I access nightly builds and documentation for ForgeRock products?

Q. How do I access the source code for the ForgeRock Authenticator app?

A. You can access the source code for the ForgeRock Authenticator app from the following repositories:

See How do I update and recompile the iOS authenticator app with custom branding in AM (All versions)? for further information on branding the iOS app. 

Q. How do I find copyright and license information for external libraries and dependencies used to build AM?

A. This information can be found in the unpacked AM war file or zip file for your AM version. Look for the third-party-copyrights.txt file in the legal-notices directory.

See Also

FAQ: Installing AM

FAQ: Upgrading AM

Source code in ForgeRock products


FAQ: Source code in DS

The purpose of this FAQ is to provide answers to commonly asked questions regarding source code and binaries in DS.

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

Frequently asked questions

Q. Where can I find the LDAP SDK for DS?

A. The LDAP SDK provides public Java APIs for connecting to DS. There are multiple versions available, however, the newer versions include more APIs to increase the functionality available. Additionally, there are dependencies between the server version and LDAP SDK in some situations: 

  • If you are building a plugin or extension, you must use the corresponding opendj-core version. For example, if you use DS 7.0.0, you must use the opendj-core-7.0.0.jar.
  • If you are building an LDAP client, you can use any version with any supported versions of DS as the SDK version is not tied to the DS version in this situation.

Each DS server release has an equivalent opendj-core-xxx.jar file in Artifactory. You can locate the required file by searching for opendj-core-xxx.jar (replacing xxx with the 3 digit release number). For example, the file for DS 6 is here: opendj-core-6.0.0.jar

You must log in using your BackStage username and password to access these files.

The Javadoc for the corresponding version lists the LDAP SDK packages available for that release.

Q. What credentials do I use to log into Bitbucket?

A. You can log into Bitbucket with your BackStage username and password. Your BackStage username is different to your email address.

Note

You can log into BackStage using either your email address or username, but you must use your username to log into Bitbucket.

You must also be authenticated to access the Maven repositories; see How do I access the ForgeRock protected Maven repositories? for further information.  

Q. How do I access nightly builds and documentation?

A. You can access nightly builds (binaries) and documentation as detailed in How do I access nightly builds and documentation for ForgeRock products?

See Also

How do I access the ForgeRock protected Maven repositories?

FAQ: Installing and configuring DS

FAQ: Upgrading DS


FAQ: Source code in IDM

The purpose of this FAQ is to provide answers to commonly asked questions regarding source code and binaries in IDM.

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

Frequently asked questions

Q. How do I access source code to customize IDM connectors?

A. The source code to customize some IDM connectors is available in repositories hosted on our Bitbucket® Server.

See Where can I find source code for IDM (All versions)? and Understanding source code access for ForgeRock products for further information.

Q. What credentials do I use to log into Bitbucket?

A. You can log into Bitbucket with your BackStage username and password. Your BackStage username is different from your email address.

Note

You can log into BackStage using either your email address or username, but you must use your username to log into Bitbucket.

You must also be authenticated to access the Maven repositories; see How do I access the ForgeRock protected Maven repositories? for further information. 

Q. How do I access nightly builds and documentation?

A. You can access nightly builds (binaries) and documentation as detailed in How do I access nightly builds and documentation for ForgeRock products?

See Also

How do I access the ForgeRock protected Maven repositories?

FAQ: Upgrading IDM


Known Issues


Blocked mirror for repositories error when building from source using Maven 3.8.1 or later

The purpose of this article is to provide assistance if you encounter "Blocked mirror for repositories" errors when building from source using Apache Maven™ 3.8.1 or later.

Symptoms

An error similar to the following is shown when the build fails:

[ERROR] Some problems were encountered while processing the POMs: [ERROR] Non-resolvable import POM: Could not transfer artifact org.glassfish.grizzly:grizzly-bom:pom:2.3.36-forgerock-0 from/to maven-default-http-blocker (http://0.0.0.0/): Blocked mirror for repositories: [forgerock-internal-releases (http://maven.forgerock.org/repo/internal-releases, default, releases), forgerock-internal-snapshots (http://maven.forgerock.org/repo/internal-snapshots, default, snapshots)] @ org.forgerock.commons:commons-bom:24.0.44, /Users/jdoe/.m2/repository/org/forgerock/commons/commons-bom/24.0.44/commons-bom-24.0.44.pom, line 318, column 25

Recent Changes

Upgraded Maven to 3.8.1 or later.

Causes

Maven 3.8.1 removes support for accessing Maven repositories over HTTP for security reasons. See Maven Release Notes - CVE-2021-26291 for further information.

Pre-7.1 releases in the ForgeRock Maven repositories use HTTP, which means they won't build using Maven 3.8.1 or later. However, ForgeRock redirects all HTTP requests for Maven repositories to HTTPS, which allows mirror repositories to be safely used.

Solution

This issue can be resolved by adding mirror repositories (using mirrorOf) to the ~/.m2/settings.xml file to redirect the mirrors referenced in the Maven error to HTTPS. You will also need to add corresponding server entries for the new mirror repositories.

The following example adds the most commonly needed mirrors, however, you may need additional mirrors (for example, forgerock-third-party) depending on what you are building. Check what mirrors are referenced in the Maven error, and add any additional mirror repositories and server entries needed to allow you to build successfully.

Example

  1. Add the following mirrors to your settings.xml file:<mirrors>    <mirror>         <id>forgerock-internal-releases-mirror</id>         <name>ForgeRock Internal Releases Repository mirror</name>         <url>https://maven.forgerock.org/repo/internal-releases</url>         <mirrorOf>forgerock-internal-releases</mirrorOf>     </mirror>     <mirror>         <id>forgerock-internal-snapshots-mirror</id>         <name>ForgeRock Internal Snapshots Repository mirror</name>         <url>https://maven.forgerock.org/repo/internal-snapshots</url>         <mirrorOf>forgerock-internal-snapshots</mirrorOf>     </mirror> </mirrors>
  2. Add the following server entries to your settings.xml file for these new ids (replacing the username/password fields with your username and encrypted password strings from the settings.xml file):<server>       <username>xxxx</username>         <password>xxxx</password>         <id>forgerock-internal-releases-mirror</id>     </server>     <server>         <username>xxxx</username>         <password>xxxx</password>         <id>forgerock-internal-snapshots-mirror</id>     </server>

See Also

How do I access the ForgeRock protected Maven repositories?

Source code in ForgeRock products

Related Training

N/A

Related Issue Tracker IDs

N/A


Building AM 7.x projects from source fail with a Failed to execute goal error

The purpose of this article is to provide assistance if you encounter a "Failed to execute goal" error when trying to build an AM 7.x project extension (such as a custom authentication node) from source. The error will reference the following dependency: org.apache.servicemix.bundles:org.apache.servicemix.bundles.java-xmlbuilder:bundle:1.1_1.

Symptoms 

Building an AM 7.x extension project (such as a custom node) from source fails.

You will see an error similar to one of the following when this happens:

[ERROR] Failed to execute goal on project [project_name]: Could not resolve dependencies for project [project_name]: Could not find artifact org.apache.servicemix.bundles:org.apache.servicemix.bundles.java-xmlbuilder:bundle:1.1_1 in forgerock-private-releases (https://maven.forgerock.org:443/repo/private-releases) -> [Help 1]

[ERROR] Failed to execute goal on project [project_name]: Could not resolve dependencies for project [project_name]: Could not transfer artifact org.apache.servicemix.bundles:org.apache.servicemix.bundles.java-xmlbuilder:bundle:1.1_1 from/to forgerock-private-releases (https://maven.forgerock.org:443/repo/private-releases): Authorization failed for https://maven.forgerock.org:443/repo/private-releases/org/apache/servicemix/bundles/org.apache.servicemix.bundles.java-xmlbuilder/1.1_1/org.apache.servicemix.bundles.java-xmlbuilder-1.1_1.bundle 403 Forbidden -> [Help 1]

Recent Changes

Upgraded to, or installed AM 7.x.

Causes

Changes were made to library dependencies in AM 7. 

As a result, this error occurs because the org.apache.servicemix.bundles:org.apache.servicemix.bundles.java-xmlbuilder dependency is missing from your Maven repository and cannot be retrieved using the default project configuration. This bundle package must be made available during the Maven build phase by adding a new Maven plugin (as explained in the solution).

Solution

This issue can be resolved by adding the following section to the project pom.xml before rebuilding your project extension:

<build> <plugins> <plugin>      <groupId>org.apache.felix</groupId>       <artifactId>maven-bundle-plugin</artifactId>       <version>4.2.1</version>       <extensions>true</extensions> </plugin> </plugins> </build>

See Also

Authentication Node Development Guide

Related Training

N/A

Related Issue Tracker IDs

N/A


Building from source fails with The exception was thrown with the wrong message when system locale is not English

The purpose of this article is to provide assistance if building from source using Apache Maven™ fails with the following exception when the system locale is not English: "FAILURE! org.testng.TestException: The exception was thrown with the wrong message". This article applies to all ForgeRock products (AM, Agents, DS, IDM and IG).

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

Symptoms

The Maven build fails and you see a message similar to the following, where the English message is shown followed by the equivalent in a different language:

  • French example: ------------------------------------------------------- T E S T S  -------------------------------------------------------  Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=96m; support was removed in 8.0  Running TestSuite  Tests run: 170, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 5.3 sec <<< FAILURE! - in TestSuite  shouldForbidChangingIntegerCache(org.forgerock.openam.scripting.StandardScriptEvaluatorTest) Time elapsed: 0.081 sec <<< FAILURE!  org.testng.TestException:  The exception was thrown with the wrong message: expected ".*Access to Java class .*? is prohibited.*" but got "L'accès à la classe Java "java.lang.Class" est prohibé. (<Unknown source>#1) in <Unknown source> at line number 1 at column number 0"
  • Spanish example: ------------------------------------------------------- T E S T S  -------------------------------------------------------  Java HotSpot(TM) 64-Bit Server VM warning: ignoring option MaxPermSize=96m; support was removed in 8.0  Running TestSuite  Tests run: 170, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 5.3 sec <<< FAILURE! - in TestSuite  shouldForbidChangingIntegerCache(org.forgerock.openam.scripting.StandardScriptEvaluatorTest) Time elapsed: 0.081 sec <<< FAILURE!  org.testng.TestException:  The exception was thrown with the wrong message: expected "Invalid value DELETE for property actionValues" but got "Valor no válido DELETE para propiedad actionValues"

Recent Changes

Changed the system locale to a non-English locale.

Causes

Some error messages are hard-coded in English. When Maven attempts to display them in a different language (as determined by your system locale), it fails and generates this exception.

Solution

This issue can be resolved using one of the following approaches:

  • Exclude the unit tests when building from source. This can be achieved using the following command: $ mvn install -DskipTests
  • Add the -Duser.language=en option to the root pom.xml file and rebuild. This option should be added to the java.surefire.options property. For example: <java.surefire.options>-Xms256m -Xmx256m -XX:MaxPermSize=96m -Duser.language=en</java.surefire.options>

See Also

Source code in ForgeRock products

Related Training

N/A

Related Issue Tracker IDs

OPENAM-8182 (Maven build fails if system locale is not en_US)


Copyright and TrademarksCopyright © 2021 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...