How To

How do I upgrade from OpenIDM 2.x to OpenIDM 3.x?

Last updated Jan 5, 2021

The purpose of this article is to provide information on upgrading from OpenIDM 2.x to OpenIDM 3.x directly, without needing to do a two stage upgrade (OpenIDM 2.x to 3.0, then OpenIDM 3.0 to 3.x).


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

Upgrading from OpenIDM 2.x to OpenIDM 3.x

To upgrade from OpenIDM 2.x to OpenIDM 3.x directly, you need to ensure you have taken account of all the changes that have occurred in OpenIDM 3.0 and OpenIDM 3.x, as outlined in the install guides:


Prior to upgrading OpenIDM, you should also read the OpenIDM Release Notes relevant to the target release and all interim releases. In particular, you should check the relevant OpenIDM Compatibility section to ascertain if your existing customizations will continue to work; this is especially important for any script changes you have made.  

The general process for upgrading from OpenIDM 2.x to OpenIDM 3.x is as follows, but you should consult the install guides for further information as needed, as your upgrade is likely to be more complex if you have many customizations to migrate:

  1. Download the OpenIDM 3.x zip file from BackStage and extract the file.
  2. Stop the OpenIDM 2.x server if it is running.
  3. Back up your OpenIDM 2.x deployment by zipping up the entire openidm/ directory.
  4. Update the file on the OpenIDM 3.x server (located in the /path/to/openidm3.x/conf/boot directory) to include any customizations you made to the same file on the OpenIDM 2.x server. Specifically you should check the following:
    • Ensure the HTTP, HTTPS and mutual authentication ports are specified in the file if you changed the default ports in your 2.x deployment; these ports were specified in the jetty.xml file (located in the /path/to/openidm2.x/conf directory) in OpenIDM 2.x but moved to the file in OpenIDM 3.x.
    • Check that the keystore and truststore passwords match the current passwords for the keystore and truststore of your OpenIDM 2.x deployment.
    • Set the following properties if your new OpenIDM 3.x deployment is going to run in a cluster; certain cluster properties are now specified in the file: openidm.instance.type openidm.scheduler.execute.persistent.schedules
  5. Update the new cluster.json file (located in the /path/to/openidm3.x/conf directory) if your new OpenIDM 3.x deployment is going to run in a cluster; the timeout and checkin settings that were previously defined in the scheduler.json file (located in the /path/to/openidm2.x/conf directory) are now defined in the new cluster.json file.
  6. Copy the contents of your /path/to/openidm2.x/security folder to your new OpenIDM 3.x deployment. You will also need to update the file to point to the relative location of your keystore.jceks and truststore security files.
  7. Merge all customizations from OpenIDM 2.x to 3.x. The affected files will vary according to the customizations you have made, but you should specifically check the following files in the /path/to/openidm/conf directory:
    • all provisioner configuration files
    • managed.json
    • repo.jdbc.json
    • sync.json
  8. Migrate any modified or custom scripts (contained in the /path/to/openidm/script directory) from OpenIDM 2.x to 3.x.
  9. Migrate all your required data; this includes internal user data, managed objects, and reconciliation and audit data.
  10. Update the allowedAuthenticationIdPatterns for the CLIENT_CERT authentication module in authentication.json as follows if you are using the OpenDJ self-signed certificate in your truststore: { "name" : "CLIENT_CERT", "properties" : { "queryOnResource" : "security/truststore", "defaultUserRoles" : [ "openidm-cert" ], "allowedAuthenticationIdPatterns" : [ "CN=localhost, O=OpenDJ Self-Signed Certificate" ] }, "enabled" : true } You will need to change this value if you are using a certificate that has been issued by a Certificate Authority.

See Also

FAQ: Upgrading IDM

How do I migrate to OpenIDM 4.x from an earlier release?

OpenIDM 3.0.0 Release Notes › What's New in OpenIDM 3.0.0

OpenIDM 3.0.0 Release Notes › OpenIDM Compatibility

OpenIDM 3.0.0 Installation Guide › Migrating to OpenIDM 3.0.0

OpenIDM 3.1.0 Release Notes › What's New in OpenIDM 3.1.0

OpenIDM 3.1.0 Release Notes › OpenIDM Compatibility

OpenIDM 3.1.0 Installation Guide › Migrating to OpenIDM 3.1.0

Related Training


Related Issue Tracker IDs


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