Upgrading IDM/OpenIDM

This book provides information on upgrading IDM/OpenIDM including recommended procedures for different upgrade scenarios and known issues.


Recommended Processes


How do I migrate my existing BPMN workflows after upgrading to IDM 5.5 or applying Security Advisory #201705?

The purpose of this article is to provide guidance on migrating existing Business Process Model And Notation™ (BPMN™) workflows in IDM/OpenIDM after upgrading to IDM 5.5 or applying Security Advisory #201705.

Migrating a BPMN Workflow

After upgrading to IDM 5.5 or applying Security Advisory #201705, existing BPMN workflows must be modified in order to to attach a scriptTaskListener to each userTask within the workflow. The scriptTaskListener must inject any required user input within the process context, making it available to other workflow stages.

The attached workflowScriptTaskHelper.xsl file can be used to assist with migration and will automatically transform basic BPMN workflows. Complex workflows or those which do not already include a userTask may require additional manual intervention:

  • On Mac® OS X® or Linux®, you must execute the following XSLT script to migrate your BPMN files:
    xsltproc workflowScriptTaskHelper.xsl path/to/your/project.bpmn20.xml  | xmllint -format -
    
  • On Microsoft® Windows®, the Microsoft Command Line Transformation Utility (msxsl.exe) can be used in conjunction with the Microsoft Core XML Services to migrate your BPMN files:
    msxsl.exe path/to/your/project.bpmn20.xml workflowScriptTaskHelper.xsl -o path/to/your/updated.bpmn20.xml
    

See Also

IDM/OpenIDM Security Advisory #201705

Integrator's Guide › Integrating Business Processes and Workflows

Related Training

N/A

Related Issue Tracker IDs

N/A


How do I upgrade DS/OpenDJ (All versions) if I have the DS/OpenDJ Password Sync Plugin for IDM/OpenIDM installed?

The purpose of this article is to provide information on upgrading DS/OpenDJ if you have the DS/OpenDJ Password Sync Plugin for IDM/OpenIDM installed.

Background Information

The password plugin configuration is specified in one of the following files depending on the plugin version:

  • Plugin version 3.5.0 and later - openidm-accountchange-plugin-sample-config
  • Plugin versions 1.0.3 and 1.1.1 - openidm-pwsync-plugin-config.ldif
Note

You must use the plugin version that corresponds to your DS/OpenDJ version. See Release Notes › Supported Connectors, Connector Servers, and Plugins for further information.

Upgrading DS/OpenDJ

You can upgrade DS/OpenDJ as follows:

  1. Back up the password plugin configuration file (openidm-pwsync-plugin-config.ldif or openidm-accountchange-plugin-sample-config, which is located in the /path/to/ds/config directory) as this contains your current configuration details.
  2. Update the Default Password Policy to remove the account-status-notification-handler attribute using a dsconfig command such as the following:
    $ ./dsconfig set-password-policy-prop --policy-name "Default Password Policy" --reset account-status-notification-handler --hostname localhost --port 4444 --bindDn "cn=Directory Manager" --bindPassword password --trustAll --no-prompt
  3. Remove the changes made to the cn=config backend when the plugin was installed using a ldapdelete command such as the following:
    $ ./ldapdelete --hostname ds1.example.com --port 4444 --bindDN "cn=Directory Manager" --bindPassword password "cn=OpenIDM Notification Handler,cn=Account Status Notification Handlers,cn=config"
  4. Stop the DS/OpenDJ instance.
  5. Delete the following files that apply to the existing plugin:
    • openidm-pwsync-plugin-config.ldif or openidm-accountchange-plugin-sample-config in the /path/to/ds/config directory.
    • 90-openidm-pwsync-plugin.ldif file in the /path/to/ds/config/schema directory; as of DS 6 and later, located in /path/to/ds/db/schema for new installs.
    • opendj-accountchange-handler-x.x.x.jar in the /path/to/ds/lib/extensions directory.
  6. Restart the DS/OpenDJ instance.
  7. Upgrade to the new version of DS/OpenDJ. See Installation Guide and Upgrading DS/OpenDJ for further information.
  8. Install the new plugin per the instructions in Password Synchronization Plugin Guide › Installing the DS Password Synchronization Plugin.
  9. Update the configuration file (openidm-pwsync-plugin-config.ldif or openidm-accountchange-plugin-sample-config depending on which version of the plugin you installed) with the details contained in the configuration file you backed up if you want to retain the same behavior you had previously.

See Also

DS (All versions) and OpenDJ 3.x fail to start after upgrade if you use the Password Sync Plugin for IDM/OpenIDM

OpenDJ Password Synchronization Plugin 1.0.3 install fails on OpenDJ 3.x

How do I troubleshoot the DS/OpenDJ Password Synchronization plugin in IDM/OpenIDM (All versions)?

Password Synchronization Plugin Guide › Synchronizing Passwords With ForgeRock Directory Services (DS)

Related Training

N/A

Related Issue Tracker IDs

N/A


Frequently Asked Questions


FAQ: Upgrading IDM/OpenIDM

The purpose of this FAQ is to provide answers to commonly asked questions regarding upgrading IDM/OpenIDM.

Frequently asked questions

Q. How can I find everything that has been fixed in a release?

A. You can look in the IDM/OpenIDM Issue Tracker to see what has been fixed against a given release. Links for recent releases are included below:

Note

The release notes also list all the key fixes that have been included as well as any known issues that are still outstanding at the time of the release: IDM 6.5 Release Notes, IDM 6 Release Notes, IDM 5.5 Release NotesIDM 5 Release Notes, OpenIDM 4.5 Release Notes and OpenIDM 4 Release Notes.

Q. Where can I find end of support life (EOSL) dates for IDM/OpenIDM?

A. The release dates and end of support life dates for IDM/OpenIDM are available from: Checking your product versions are supported

Q. How do I migrate to a later version of IDM/OpenIDM with a MySQL™ database?

A. As of OpenIDM 4.5, migrating your database is handled by the update process. See Installation Guide › Updating Servers for further information.

In OpenIDM 4 and earlier, you have two options: you can either migrate your existing database or start with a new database and export your data. See How do I migrate to OpenIDM 4.x from an earlier release? for further information.

See Also

How do I migrate my existing BPMN workflows after upgrading to IDM 5.5 or applying Security Advisory #201705?

FAQ: IDM/OpenIDM compatibility with third-party products

FAQ: Installing and configuring IDM/OpenIDM

Upgrading IDM/OpenIDM

Related Training

ForgeRock Identity Management Core Concepts (IDM-400)


FAQ: Installing and configuring IDM/OpenIDM

The purpose of this FAQ is to provide answers to commonly asked questions regarding installing and configuring IDM/OpenIDM.

Frequently asked questions

Q. Is IDM/OpenIDM compatible with Oracle Java Development Kit (JDK) 9 or later?

A. No, Oracle JDK 9 is not currently supported. You should only use supported versions to prevent compatibility issues. Future versions of IDM will be targeting compatibility with Java 11: OPENIDM-11526 (Support JDK11).

Q. Is IDM/OpenIDM compatible with Oracle JDK 8?

A. Yes. As of OpenIDM 4, Oracle JDK 8 is fully supported. You should only use supported versions to prevent compatibility issues, such as the configimport failing.

Q. Can IDM/OpenIDM be used with OpenJDK?

A. Yes, OpenJDK is supported in IDM/OpenIDM. See Release Notes › Preparing the Java Environment for details of versions.

Q. How do I integrate IDM, AM and DS?

A. You should refer to ForgeRock Identity Platform Version 6: Integrating IDM, AM, and DS or Integrating IDM, AM, and DS (version 5.5), which collects the information you need to set up integration in one place. For additional features, refer to the following chapters from IDM documentation: Samples Guide › Integrating IDM With the ForgeRock Identity Platform and the Integrator's Guide › Setting Up User-Managed Access (UMA), Trusted Devices, and Privacy.

See How does the OIDC authorization flow work when IDM (All versions) is integrated with AM? for further information.

Q. Do I need to change the default symmetric encryption key for production?

A. No, you do not. IDM/OpenIDM generates a symmetric key and a private key the first time the server is started. See How do I change the symmetric key in IDM/OpenIDM (All versions)? for further information.

However, you should change the default keystore password as per: How do I change the default keystore password in IDM/OpenIDM (All versions)?

Q. Does IDM/OpenIDM support encryption keys with 256-bit AES encryption?

A. Yes, IDM/OpenIDM does support keys with 256-bit AES encryption; however, Java does not support keys with 256-bit AES encryption by default; only 128-bit AES encryption is supported.

If you want to use keys with 256-bit AES encryption, you must install the Oracle Java JCE unlimited strength jars. These jars can be downloaded from the following links depending on which Java version you are using:

Q. How do I configure IDM/OpenIDM for case insensitive searching?

A. IDM/OpenIDM is case-sensitive, but this can cause issues where valid entries are not found due to their case. This issue also affects queries done using queryFilter as the case-sensitivity of queryFilter depends on the repository's collation. You can resolve this by configuring the repository for case sensitivity as detailed in Integrator's Guide › Configuring Case Sensitivity For Data Stores.

Q. Can IDM/OpenIDM be configured to use multiple OpenICF Connector servers and failover with Active Directory Domain Controllers?

A. No, IDM/OpenIDM can only use one OpenICF Connector server at a time. For failover purposes, you should have two or more Active Directory Domain Controllers (DC) with the OpenICF Connector server installed and if one becomes unavailable, your system administrator should change the target IP to another available DC.

Q. Can you configure IDM/OpenIDM reconciliation to continue implicit synchronization even when failure occurs?

A. No, IDM/OpenIDM performs implicit synchronization on an all or nothing basis according to the failure compensation configuration. There is no way to have implicit synchronization occur on specific objects within a mapping but not others.

Q. How do I configure IDM/OpenIDM to handle large data sets for reconciliation?

A. You should refer to the documentation for information on improving reconciliation performance in your version of IDM/OpenIDM:

See How do I identify reconciliation performance issues in IDM/OpenIDM (All versions)? for further information on troubleshooting reconciliation performance. 

See Also

FAQ: General IDM/OpenIDM

FAQ: IDM/OpenIDM compatibility with third-party products

FAQ: Upgrading IDM/OpenIDM

FAQ: Scripts in IDM/OpenIDM

Installation Guide

Integrator's Guide

Related Training

ForgeRock Identity Management Core Concepts (IDM-400)


Known Issues


Failed to load checksum file from archive error in IDM (All versions) and OpenIDM 4.x

The purpose of this article is to provide assistance if you encounter a "Failed to load checksum file from archive" error in IDM/OpenIDM. This error can occur during the install or upgrade process.

Symptoms

The following error is shown when upgrading from OpenIDM 4.0:

org.forgerock.json.resource.InternalServerErrorException: Server Error {"code":500,"reason":"Internal Server Error","message":"Failed to load checksum file from archive."} 
   at org.forgerock.json.resource.ResourceException.newResourceException(ResourceException.java:239) 
   at org.forgerock.json.resource.ResourceException.getException(ResourceException.java:330) 
   at org.forgerock.openidm.shell.impl.HttpRemoteJsonResource.handle(HttpRemoteJsonResource.java:373) 
   at org.forgerock.openidm.shell.impl.HttpRemoteJsonResource.action(HttpRemoteJsonResource.java:131) 
   at org.forgerock.openidm.shell.impl.UpdateCommand$GetArchiveDataStepExecutor.execute(UpdateCommand.java:318) 
   at org.forgerock.openidm.shell.impl.UpdateCommand.execute(UpdateCommand.java:194) 
   at org.forgerock.openidm.shell.impl.RemoteCommandScope.update(RemoteCommandScope.java:199) 

You may also see an error similar to the following in the IDM/OpenIDM log:

Oct 04, 2016 11:15:27 AM org.forgerock.openidm.servlet.internal.ServletConnectionFactory$4 handleException 
WARNING: Resource exception: 500 Internal Server Error: "Failed to load checksum file from archive." org.forgerock.json.resource.InternalServerErrorException: Failed to load checksum file from archive. 
   at org.forgerock.openidm.maintenance.impl.UpdateService.handleListAvailable(UpdateService.java:151) 
   at org.forgerock.openidm.maintenance.impl.UpdateService.handleAction(UpdateService.java:128) 
   at org.forgerock.json.resource.Router.handleAction(Router.java:241) 

Recent Changes

Installed, or upgraded to IDM 5 or later.

Installed, or upgraded to OpenIDM 4.x.

Causes

The checksum file is missing.

The checksum file is used by the IDM/OpenIDM Update mechanism. It should not be modified and contains the checksums of all the files distributed with the release, which are then used to identify modified files and/or files which do not originate from ForgeRock during the upgrade. See Installation Guide › Updating Servers › Files Changed During the Update Process for further information.

Caution

It is important to ensure the checksum file is deployed when installing or upgrading IDM/OpenIDM; failing to do so will prevent you updating IDM/OpenIDM in the future.

Solution

This issue can be resolved by ensuring the .checksums.csv file is located within the root of the IDM/OpenIDM installation directory. If it does not exist, you should extract the original file from the IDM or OpenIDM 4.x installation bundle and copy it to your IDM/OpenIDM installation directory.

See Also

Installation Guide › Updating Servers › Files Changed During the Update Process

Installation Guide › Updating Servers › An Overview of the Update Process

Related Training

N/A

Related Issue Tracker IDs

OPENIDM-5290 (Archive that does not have checksums file should be listed as rejected by action=available)


Custom endpoints that worked in previous versions of OpenIDM fail in IDM (All versions) and OpenIDM 4.x

The purpose of this article is to provide assistance if you find that previously working custom endpoints fail after upgrading to IDM/OpenIDM with a 200 OK "Malformed JSON: Expected ',' instead of ' '." message.

Symptoms

The following error is shown in the browser when calling the custom endpoint:

{"code":200,"reason":"OK","Malformed JSON: Expected ',' instead of ''."}

Recent Changes

Upgraded to IDM 5 or later.

Upgraded to OpenIDM 4.x.

Causes

OpenIDM 4 has been updated to use CREST 3. Specifically, changes introduced by CREST-328 (The REST API should always include _id and _rev regardless of the field filtering) mean that scripts called by custom endpoints must now return a JSON object rather than a string. Any scripts called by custom endpoints that return just a string will fail with this error.

Solution

This issue can be resolved by updating your scripts to return a JSON object instead of a string.

For example, if your script currently has the following return code:

return openidm.decrypt(encrypted); 

You can update it as follows:

return { "JSONobjectID" : openidm.decrypt(encrypted) };

When you call the associated custom endpoint, you will see the expected response with an extra "_id" attribute due to these changes, for example:

{ 
"_id": "", 
"JSONobjectID": "decryptedOutput" 
}

See Also

OpenIDM 4 Release Notes › OpenIDM Compatibility › Major Changes to Existing Functionality (Updated REST API)

Related Training

N/A

Related Issue Tracker IDs

CREST-328 (The REST API should always include _id and _rev regardless of the field filtering)


Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...