How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I install an IDM patch (All versions) supplied by ForgeRock support?

Last updated Mar 22, 2022

The purpose of this article is to provide information on installing an IDM patch that has been supplied by ForgeRock support. It also includes the necessary steps for installing UI patches (Admin or End User).


1 reader recommends this article

Overview

The instructions for installing IDM patches vary according to the type of patch and what version you are using:

Note

Regardless of the patch type or version, you must delete the felix cache after applying the patch and restart IDM.

End User UI in IDM 6.5 and later

The End User UI is continually updated to include any bug fixes and is available from GitHub; you can pick up the latest version and build it per the README.

Where can I find source code for IDM? (Using the End User UI source code) provides details about the End User UI version for each IDM release.

Installing a non-UI patch (All versions)

Typically, a patch for IDM includes one or more replacement bundles that need to be placed in the path/to/idm/bundle directory. The bundles in this directory have the following naming convention: openidm-<component>--<openidm_version>.jar, for example: openidm-config-6.5.0.jar or openidm-repo-jdbc-6.0.0.jar

A patched bundle includes -PATCH in the filename to make it easier to identify which bundles have been patched, for example, a patch for openidm-repo-jdbc-6.5.0.jar is named openidm-repo-jdbc-6.5.0-PATCH.jar. This patch naming convention changed at the end of 2020, so patches delivered before this time don't include -PATCH in the filename.

We also provide the shasum so you can verify that the files are not corrupted.

You can install an IDM patch as follows:​

  1. Shutdown the IDM instance. $ cd /path/to/idm $ ./shutdown.sh
  2. Back up the existing versions of the files in the /path/to/idm/bundle directory that have been supplied in the patch.
  3. Delete these files once they have been backed up.
  4. Copy the replacement files supplied in the patch to the /path/to/idm/bundle directory.
  5. Delete the felix cache: $ cd /path/to/idm $ rm -rf felix-cache/*
  6. Start the IDM server: $ cd /path/to/idm $ ./startup.sh

Installing an Admin UI patch (All versions)

Typically, an Admin UI patch for IDM includes the following replacement bundle: openidm-ui-admin-<version>.jar

We also provide the shasum so you can verify that the files are not corrupted.

Caution

If you have customized the UI (for example, made changes to the logo, css or similar), deleting the ui/admin directory will remove these customizations. In which case, you will need to reapply your customizations after you have installed the patch.

You can install an Admin UI patch as follows:​

  1. Shutdown the IDM instance. $ cd /path/to/idm $ ./shutdown.sh
  2. Back up and delete the following file and corresponding ui directory:
    • /path/to/idm/bundle/openidm-ui-admin-*.jar
    • /path/to/idm/ui/admin
  3. Copy the replacement file supplied in the patch to the /path/to/idm/bundle directory.
  4. Navigate to the /path/to/idm/ui/admin directory and execute the following command: $ cd /path/to/idm/ui/admin $ jar -xvf /path/to/idm/bundle/openidm-ui-admin-<version>.jar
  5. Delete the felix cache: $ cd /path/to/idm $ rm -rf felix-cache/*
  6. Reapply any customizations to the ui/admin directory.
  7. Start the IDM server: $ cd /path/to/idm $ ./startup.sh

Installing an End User UI patch (IDM 6.5 and later)

Typically, an End User UI patch for IDM 6.5 and later is delivered as a zip file.

Caution

If you have customized the UI (for example, made changes to the logo, css or similar), replacing the contents of the ui/enduser directory will remove these customizations. In which case, you will need to reapply your customizations after you have installed the patch.

You can install an IDM UI patch as follows:​

  1. Shutdown the IDM instance. $ cd /path/to/idm $ ./shutdown.sh
  2. Back up the /path/to/idm/ui/enduser directory.
  3. Extract the patch zip to a temporary location: $ unzip /tmp/patch.zip
  4. Replace the contents in the /path/to/idm/ui/enduser directory with the contents of the extracted zip.
  5. Delete the felix cache: $ cd /path/to/idm $ rm -rf felix-cache/*
  6. Start the IDM server: $ cd /path/to/idm $ ./startup.sh

Installing an End User UI patch (Pre-IDM 6.5)

Typically, an End User UI patch for IDM includes the following replacement bundle: openidm-ui-enduser-<version>.jar

We also provide the shasum so you can verify that the files are not corrupted.

Caution

If you have customized the UI (for example, made changes to the logo, css or similar), deleting the ui/selfservice directory will remove these customizations. In which case, you will need to reapply your customizations after you have installed the patch.

You can install an IDM UI patch as follows:​

  1. Shutdown the IDM instance. $ cd /path/to/idm $ ./shutdown.sh
  2. Back up and delete the following file and corresponding ui directory:
    • /path/to/idm/bundle/openidm-ui-enduser-*.jar
    • /path/to/idm/ui/selfservice
  3. Copy the replacement file supplied in the patch to the /path/to/idm/bundle directory.
  4. Navigate to the /path/to/idm/ui/selfservice directory and execute the following command: $ cd /path/to/idm/ui/selfservice $ jar -xvf /path/to/idm/bundle/openidm-ui-enduser-<version>.jar
  5. Delete the felix cache: $ cd /path/to/idm $ rm -rf felix-cache/*
  6. Reapply any customizations to the ui/selfservice directory.
  7. Start the IDM server: $ cd /path/to/idm $ ./startup.sh

ForgeOps (ForgeRock DevOps) Deployments

If you are using the ForgeOps deployment model, you need to create a custom Docker image that includes the replacement IDM bundles and/or extracted contents of the End User UI zip. 

Please see Docker Image Development for instructions; this will require you to test the patch in a non-Kuberenetes environment first. 

See Also

ForgeRock Maintenance Release Policy

Related Training

N/A

Related Issue Tracker IDs

N/A


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