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/OpenDJ (All versions) 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. It depends on what version you are migrating to:

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) 11?

A. Yes, as of IDM 6.5, Oracle JDK 11 is supported. You should only use supported versions to prevent compatibility issues.

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 and as of Java 9, so does Java. With earlier versions of Java, you must install the Oracle Java JCE unlimited strength jars if you want to use keys with 256-bit AES encryption. See Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files Download for further information and links to download the jars.

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


Upgrade fails with an Error encountered while pausing the job scheduler in IDM 5.5.0.x, 5.5.1, 5.5.1.1, 6.0.0.0, 6.0.0.1, 6.0.0.2 or 6.0.0.3

The purpose of this article is to provide assistance if IDM upgrade fails with "Error encountered while pausing the job scheduler". The following exception is seen in the logs during a failed upgrade or if you try to pause the scheduler via a REST call, "PreconditionFailedException: Update rejected as current Object revision xx is different than expected by caller (xx), the object has changed since retrieval".

Symptoms

The upgrade fails when running the update command with the --skipRepoUpdatePreview option, for example:

$ ./cli.sh update --acceptLicense --skipRepoUpdatePreview --user openidm-admin:openidm-admin --url http://localhost:8080/openidm IDM-5.5.1.0.zip

The following error is shown in response to this update command:

Starting shell in /path/to/openidm
Nov 20, 2018 11:03:57 AM org.forgerock.openidm.core.FilePropertyAccessor loadProps
INFO: Using properties at /path/to/openidm/conf/boot/boot.properties
License was accepted via command line argument.
Repository update preview was skipped.
Pausing the Scheduler 
org.forgerock.json.resource.InternalServerErrorException: Response is not application/json 
   at org.forgerock.json.resource.http.CrestAdapter.loadJsonValueContent(CrestAdapter.java:394) 
   at org.forgerock.json.resource.http.CrestAdapter.lambda$handleAction$0(CrestAdapter.java:180) 
   at org.forgerock.util.CloseSilentlyFunction.apply(CloseSilentlyFunction.java:53) 
   at org.forgerock.util.CloseSilentlyFunction.apply(CloseSilentlyFunction.java:29) 
   at org.forgerock.util.promise.PromiseImpl.lambda$then$6(PromiseImpl.java:369) 
   ...
Error encountered while pausing the job scheduler. 
ERROR: Error during execution. The state of OpenIDM is now unknown. Last Attempted step was PAUSING_SCHEDULER. Now attempting recovery steps. 
Exiting maintenance mode... 
No longer in maintenance mode. 
Resuming the job scheduler. 
org.forgerock.json.resource.InternalServerErrorException: Response is not application/json 
   at org.forgerock.json.resource.http.CrestAdapter.loadJsonValueContent(CrestAdapter.java:394) 
   at org.forgerock.json.resource.http.CrestAdapter.lambda$handleAction$0(CrestAdapter.java:180) 
   at org.forgerock.util.CloseSilentlyFunction.apply(CloseSilentlyFunction.java:53) 
   at org.forgerock.util.CloseSilentlyFunction.apply(CloseSilentlyFunction.java:29) 
   at org.forgerock.util.promise.PromiseImpl.lambda$then$6(PromiseImpl.java:369) 
   ...
Trouble attempting to resume scheduled jobs. Please check that the scheduler is resumed. 
WARN: Failed a recovery step ENABLE_SCHEDULER, continuing on with recovery. 

If you have FINE logging enabled, you will see the following in the IDM log when this happens:

Nove 20, 2018 11:41:11 AM org.forgerock.openidm.repo.jdbc.impl.JDBCRepoService update
FINE: ResourceException in update of scheduler/jobGroups/scheduler-service-group
org.forgerock.json.resource.PreconditionFailedException: Update rejected as current Object revision 51 is different than expected by caller (54), the object has changed since retrieval.
   at org.forgerock.openidm.repo.jdbc.impl.GenericTableHandler.update(GenericTableHandler.java:522)
   at org.forgerock.openidm.repo.jdbc.impl.JDBCRepoService.update(JDBCRepoService.java:436)
   at org.forgerock.openidm.quartz.impl.RepoJobStore.updateGroupWrapper(RepoJobStore.java:504)
   at org.forgerock.openidm.quartz.impl.RepoJobStore.pauseOrResumeGroupWrapper(RepoJobStore.java:1004)
   at org.forgerock.openidm.quartz.impl.RepoJobStore.pauseTriggerGroup(RepoJobStore.java:1043)
   at org.forgerock.openidm.quartz.impl.RepoJobStore.pauseAll(RepoJobStore.java:942)
Note

The PreconditionFailedException error above also occurs if you make a REST call to the scheduler/job?_action=pauseJobs endpoint directly as detailed in the Integrator's Guide › Pausing Scheduled Jobs.

Recent Changes

Upgraded to IDM 5.5.0.x, 5.5.1, 5.5.1.1, 6.0.0.0, 6.0.0.1, 6.0.0.2 or 6.0.0.3

Causes

During the upgrade, IDM attempts to pause the scheduler by making a REST call to the scheduler/job?_action=pauseJobs endpoint. This call fails to stop the running scheduler jobs and results in an infinite loop that causes an org.forgerock.json.resource.PreconditionFailedException. This exception states that the expected version does not match the current version for an update in the repository and causes the upgrade to fail.

The same infinite loop occurs if you make a REST call directly to the scheduler/job?_action=pauseJobs endpoint.

Solution

This issue can be resolved by upgrading to IDM 5.5.1.2 or IDM 6.0.0.4 or later; you can download this from BackStage.

Workaround

You can workaround the upgrade issue by removing all the schedules, running the upgrade again and then re-creating any schedules you need:

  1. Use the following curl command to return information about the existing scheduler jobs before deleting them:
    $ curl -u openidm-admin:openidm-admin "http://localhost:8080/openidm/scheduler/job?_queryFilter=true&_prettyPrint=true"
    
  2. Shutdown the IDM instance.
    $ cd /path/to/idm
    $ ./shutdown.sh
  3. Clear the scheduler tables in the repository, for example in MySQL:
    delete from schedulerobjects;
    delete from schedulerobjectproperties;
  4. Start the IDM server:
    $ cd /path/to/idm
    $ ./startup.sh
  5. Perform the upgrade again, for example:
    $ ./cli.sh update --acceptLicense --skipRepoUpdatePreview --user openidm-admin:openidm-admin --url http://localhost:8080/openidm IDM-5.5.1.0.zip
    
  6. Re-create any in-memory scheduler jobs based on the scheduler information returned in step 1 (file-based schedules are automatically re-created). You can create them using a PUT or POST request to the scheduler/job endpoint. See Integrator's Guide › Defining a Schedule for further information.

See Also

FAQ: Upgrading IDM/OpenIDM

Upgrading IDM/OpenIDM

Integrator's Guide › Scheduling Tasks and Events

Integrator's Guide › Command-Line Interface

Related Training

N/A

Related Issue Tracker IDs

OPENIDM-11666 (Error Pausing / Resuming schedules when upgrading)

OPENIDM-11174 (Unable to resume scheduler jobs after successful pause)

OPENIDM-11265 (Unable to pause scheduler jobs with REST call)


Failed to load checksum file from archive error in 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 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 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 OpenIDM 4.x.

Causes

The checksum file is missing.

The checksum file is used by the 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 › OpenIDM Update Checksums for further information.

Caution

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

Solution

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

See Also

Installation Guide › An Overview of the OpenIDM Update Process

Installation Guide › OpenIDM Update Checksums

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 OpenIDM 4.x

The purpose of this article is to provide assistance if you find that previously working custom endpoints fail after upgrading to OpenIDM 4.x 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 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 › 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 - 2019 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...