PingIDM 8.0.0

Incompatible changes

When you update to IDM 8.0.0 from the last major version, the following changes could impact existing deployments. Adjust existing scripts, files, clients, and so on, as necessary. You should also review Deprecation notices.

If you are upgrading from an older release, review the changed functionality from all releases after your current version of IDM.

For previous releases, the information could be outdated or superseded.

Changes between IDM 7.5.x and 8.0.0

Embedded Jetty web server upgrade

The embedded Jetty web server has been upgraded to Jetty 12.0.16, and jetty.xml is no longer supported in this IDM release. Learn more in Embedded Jetty configuration.

When serving SSL requests, Jetty 12.0.16 checks that the incoming host header matches the server certificate’s subject and will return a 400 Bad Request error on a mismatch. If you’re upgrading to IDM 8.0, you must ensure your IDM server certificate subject matches the host name used by your deployment.

Felix HTTP Jetty upgrade

Felix HTTP Jetty has been upgraded to Jetty 12.1.0.

Servlet Specification upgrade

Servlet Specification has been upgraded to 6.0.

Jetty thread pool settings

You can now configure Jetty thread pool settings in conf/webserver.json.

Gzip compression settings

You can now configure Gzip compression for HTTP responses in conf/webserver.json.

Secure protocol configuration

You can now configure Secure protocol settings in conf/webserver.listener-*json.

Embedded DS repository

The embedded DS repository is no longer included with IDM. Before you can use IDM, you must select and configure a repository.

Logback

PingIDM now uses Logback to generate its server logs. You will need to add logback.xml to your configuration when updating. Learn more in Server logs.

Standalone end-user UI not bundled with PingIDM

The end-user UI is no longer bundled with PingIDM. You can download and install the end-user UI separately from the GitHub repository: ForgeRock/end-user-ui. Learn more in the End-user UI.

Array comparison

Starting with IDM 7.3, unordered array comparison became the default behavior. For this release of IDM, ordered array comparison is the default behavior, restoring the default behavior prior to IDM 7.3.

You can now use the comparison managed object schema configuration property to choose how JSON array comparisons are made with regard to array order.

Learn more about managed object schema properties and array comparison.

Java 21 support

Previously, running IDM required Java 17. You can now use Java 17 or Java 21. Learn more in Java requirements.

Changes between IDM 7.4.x and 7.5.0

Workflow engine upgrade

The Flowable embedded workflow engine has been upgraded to version 6.8.0. If you are upgrading from a previous version of IDM and use workflow, this upgrade requires one or more incremental upgrade scripts. For more information, refer to Upgrade an existing repository.

Array schema fields default to item type string

Schema fields defined as type array are required to have an item type defined as of IDM 7.4.0. IDM 7.5.0 defaults the item type to string to avoid startup issues if the type is not defined.

populateDefaults flag removed from secrets configuration

The sample secrets configuration (secrets.json) no longer includes the populateDefaults flag. It is safe to remove this from your secrets configuration.

Java 17 required

Running IDM requires Java 17. Learn more in Java requirements.

Legacy hashing algorithms removed from the Admin UI

MD5 and SHA-1 are supported for legacy reasons, but should not be used in production environments and have been removed from the Admin UI. Learn more in Salted hash algorithms.

Secret store class renamed

The org.forgerock.openidm.secrets.config.FileBasedStore class has been deprecated and replaced by org.forgerock.openidm.secrets.config.KeyStoreSecretStore. The old class is currently an alias.

Changes between IDM 7.4.0 and 7.4.1

Workflow engine upgrade

The Flowable embedded workflow engine has been upgraded to version 6.8.0. If you are upgrading from a previous version of IDM and use workflow, this upgrade requires one or more incremental upgrade scripts. For more information, refer to Upgrade an existing repository.

Changes between IDM 7.3.x and 7.4.0

IDM requires JDK 11.0.20 or higher

If you try to run this version of IDM using an older release of JDK, the following error displays:

SEVERE: Error loading keystore
java.io.IOException: Invalid keystore format
at java.base/sun.security.provider.JavaKeyStore.engineLoad(JavaKeyStore.java:667)
at java.base/sun.security.util.KeyStoreDelegator.engineLoad(KeyStoreDelegator.java:222)
at java.base/java.security.KeyStore.load(KeyStore.java:1479)
at org.forgerock.security.keystore.KeyStoreBuilder.build(KeyStoreBuilder.java:228)
at org.forgerock.openidm.secrets.keystore.KeyStoreRepository.load(KeyStoreRepository.java:59)
at org.forgerock.openidm.secrets.config.ConfigSupport.asKeyStoreHolder(ConfigSupport.java:95)
at org.forgerock.openidm.secrets.config.StoreSupport.asKeyStoreHolder(StoreSupport.java:61)
at org.forgerock.openidm.secrets.config.FileBasedStore.asKeyStoreHolder(FileBasedStore.java:18)
...

For a complete list of supported Java versions, refer to Java requirements.

The DB2 driver is now OSGi-compliant

When using IDM with a DB2 database, you previously had to create an OSGi-compliant driver. The driver included with DB2 is now compliant.

For more information, refer to:

Changes between IDM 7.3.0 and 7.3.1

Workflow engine upgrade

The Flowable embedded workflow engine has been upgraded to version 6.8.0. If you are upgrading from a previous version of IDM and use workflow, this upgrade requires one or more incremental upgrade scripts. For more information, refer to Upgrade an existing repository.

Changes between IDM 7.2.x and 7.3.0

Synchronization JSON array comparison is order-agnostic

JSON array comparison during sync is now order-agnostic. This change could negate the need for certain custom scripts within mappings. For example, scripts that were previously required to sort ldapGroups values to avoid unnecessary target object updates.

Attribute encryption on assignments

Assignment attributes are now encrypted if the corresponding connector attribute indicates confidentiality, based on the attribute’s nativeType (such as JAVA_TYPE_GUARDEDSTRING or JAVA_TYPE_GUARDED_BYTE_ARRAY). As part of this change, the managed assignment object now includes the following property:

"attributeEncryption" : { }

If attributeEncryption is not present, the assignment attributes are not encrypted. If the property is present but empty, it will default to IDM’s default encryption cipher. To specify a different cipher, add the cipher property. For example:

"attributeEncryption" : {
  "cipher" : "AES/CBC/PKCS5Padding"
}

Additionally, secrets.json has a new secret: idm.assignment.attribute.encryption.

Changes between IDM 7.1.x and IDM 7.2.0

Default onDelete behavior

The default onDelete behavior previously called a file-based script, onDelete-roles.js. This has been removed from the managed object configuration.

Felix and OSGi upgrades

IDM has upgraded to OSGi Core 8.0 and Felix Framework 7.0.0.

JMS 2.0 upgrade

The samples that use the Java Message Service (JMS) have been upgraded to use the 2.0 API and Apache ActiveMQ Artemis:

PATCH request exceptions

Previously, illegal PATCH requests could return a 400 or 500 exception. In such cases, IDM now returns a 400 status.

Policy enforcement on role name

The name property of a managed role is now subject to the uniqueness policy by default. This means that you cannot create multiple roles with the same name. To change this behavior, adjust the policy validation on the role property in your managed object configuration.

Precedence in locales in the self-registration email template

Previously, the defaultLocale specified in the Self-Registration Email Template configuration took precedence. As of IDM 7.2, locales specified as preferredLocales in the Accept-Language header take precedence over the defaultLocale.

Paused queued synchronization for unavailable routes

Synchronization queue processing for a mapping is now paused if either the source or target system route are unregistered. For more information, see Configure queued synchronization.

Embedded workflow database

Previously, you could use the Flowable workflow engine’s embedded H2 database for demo and testing purposes. IDM no longer includes this database. Before you use workflow, you must install a JDBC repository.

Learn more in Enable workflows.

Default MySQL connection driver

The default JDBC Connection Configuration now uses the connection driver from MySQL 8.1 (com.mysql.cj.jdbc.Driver).

Changes between IDM 7.1.4 and 7.1.6

No additional incompatible changes were made between 7.1.4 and 7.1.6.

Changes between IDM 7.1.2 and 7.1.4

No additional incompatible changes were made between 7.1.2 and 7.1.4.

Changes between IDM 7.1.0 and 7.1.2

Embedded workflow database

Previously, you could use the Flowable workflow engine’s embedded H2 database for demo and testing purposes. IDM no longer includes this database. Before you use workflow, you must install a JDBC repository.

Learn more in Enable workflows.

Workflow version update

Previously, workflows would break when upgrading from version 7.0.2 to 7.1.0 of IDM, because of out-of-sync versions of the Flowable workflow engine. This is fixed in version 7.1.2 of IDM. If you are upgrading IDM from version 7.0, please use IDM version 7.1.2 or higher.

Changes between IDM 7.0.x and 7.1.0

Data format change for external DS repositories

For external DS repositories with explicitly mapped managed objects, the stored data format has changed for certain data types.

In IDM versions prior to 7.1, certain property values were always considered as strings, so the returned JSON format of a managed object would look something like this:

{
  "boolean": "true",
  "integer": "12345",
  "timestamp": "20210315010101Z",
  "json": "{\"key\":\"value\"}"
}

In IDM 7.1, these properties are returned with the correct data type, so a similar object in IDM 7.1 looks something like this:

{
  "boolean": true,
  "integer": 12345,
  "timestamp": "2021-03-15T01:01:01Z",
  "json": { "key": "value" }
}

This change doesn’t affect new deployments. If you are upgrading an existing deployment with an external DS repository with explicit object mappings, you should test this change and adapt your scripts and REST API calls, as necessary.

This change affects the following data types:

  • Booleans: from string to JSON boolean

    Affected OIDs: 1.3.6.1.4.1.1466.115.121.1.7 and 1.3.6.1.4.1.36733.2.1.3.3.7

  • Integers: from string to JSON integer

    Affected OIDs: 1.3.6.1.4.1.1466.115.121.1.27 and 1.3.6.1.4.1.36733.2.1.3.3.27

  • Generalized time: from string in LDAP generalized time format, to string in ISO 8601 format

    Affected OIDs: 1.3.6.1.4.1.1466.115.121.1.24 and 1.3.6.1.4.1.36733.2.1.3.3.24

  • JSON: from JSON embedded in a string to structured JSON

    Affected OIDs: 1.3.6.1.4.1.36733.2.1.3.1

If you want to retain the legacy behavior, set the following property in conf/system.properties:

openidm.ds.rest2ldap.ignoreSchema.enabled=true

This is not recommended in a production deployment and should be used only temporarily, as part of a plan to adapt to these changes.

Audit handler changes

The JsonStdoutAuditEventHandler is now pre-configured in the standard audit configuration, but is disabled by default.

Previously, to enable or disable audit handlers, you needed to modify conf/audit.json directly. Now, you can set the following properties in the resolver/boot.properties file to true or false:

  • openidm.audit.handler.json.enabled

  • openidm.audit.handler.stdout.enabled

  • openidm.audit.handler.repo.enabled

Learn more in:

Parameterized HTTP and HTTPS enablement

Previously, to enable or disable HTTP or HTTPS, you could modify conf/config.properties directly. Now, you can set the following properties in the resolver/boot.properties file to true or false:

  • openidm.https.enabled

  • openidm.http.enabled

Learn more in Property value substitution.

Parameterized Felix web console credentials

Previously, to change the Felix web console credentials, you could modify the conf/felix.webconsole.json file directly. Now, you can set the following properties in the resolver/boot.properties file:

  • openidm.felix.webconsole.username

  • openidm.felix.webconsole.password

Notification changes

Notifications are now disabled by default. Previously, to enable or disable notifications, you could modify the applicable conf/notificationType.json file directly. Now, you can set the following properties in the resolver/boot.properties file to true or false:

  • openidm.notifications.passwordUpdate

  • openidm.notifications.profileUpdate

  • openidm.notifications

Learn more in Configure notifications.

Moved configuration files

The following files have been moved from the /path/to/openidm/conf/ directory:

  • auth.profile.json moved to /path/to/openidm/samples/example-configurations/self-service/.

  • jsonstore.json moved to /path/to/openidm/samples/example-configurations/self-service/.

  • identityProviders.json moved to /path/to/openidm/samples/example-configurations/self-service/.

Improved validateProperty error handling

Previously, API requests containing the validateProperty action to unknown resources or those with invalid POST body content could result in an invalid true response, or a generic 500 Internal Server Error. Both of these situations now return a 400 Bad Request Error with an explanation.

Error comparison

  • BEFORE

  • AFTER

{
  "code": 500,
  "reason": "Internal Server Error",
  "message": "TypeError: Cannot call method "hasOwnProperty" of null",
  "detail": {}
}
{
  "code": 400,
  "reason": "Bad Request",
  "message": "object and properties were not provided in request content, and they are unable to be retrieved.",
  "detail": {}
}

Changes to router.json

The default router.json file no longer includes system in the matching pattern.

Changes between IDM 6.5.x and 7.0.0

Embedded workflow database

Previously, you could use the Flowable workflow engine’s embedded H2 database for demo and testing purposes. IDM no longer includes this database. Before you use workflow, you must install a JDBC repository.

Learn more in Enable workflows.

New workflow engine

The Activiti workflow engine has been replaced with Flowable. Current workflow definitions will continue to work with the new engine in compatibility mode, but all new workflow definitions must be written for Flowable. Learn more in Workflow definition comparison.

If you are using MySQL for the workflow database, the following apply:

  • You must use MySQL version 5.6.4 or later. If you are using an older version, perform the MySQL upgrade before upgrading to IDM 7 or later. For additional information, see the Flowable Note for MySQL users.

  • Flowable automatically upgrades the database schema and can encounter non-recoverable errors related to date settings. Before you start IDM 7 or later for the first time, remove the SQL_MODE settings NO_ZERO_IN_DATE and NO_ZERO_DATE. Example SQL command:

    mysql -uroot -ppassword

set GLOBAL SQL_MODE='';

use openidm;
set SQL_MODE='';

    After you complete the upgrade process, you can restart MySQL and your original settings should be restored.

Changes to boot.properties

Prometheus monitoring

Monitoring using Prometheus is no longer achieved with a specific access role. The openidm/metrics/prometheus endpoint is now protected by a basic authentication filter, using credentials set in the resolver/boot.properties file. Learn more in Prometheus endpoint.

Debugging information for Groovy scripts

In previous releases, setting javascript.exception.debug.info=true in the boot.properties file enabled additional debug information, including line numbers and file names for JavaScript exceptions. In this release, setting groovy.exception.debug.info=true lets you gather comparable debug information for Groovy scripts.

Added properties

These properties have been added to resolver/boot.properties:

  • openidm.servlet.upload.alias=/upload and openidm.servlet.export.alias=/export: Sets the REST endpoints for the bulk import feature.

  • openidm.admin.password=openidm-admin: Lets you change the password of the administrative user before startup.

Removed properties

These properties have been removed from resolver/boot.properties:

  • openidm.script.javascript.debug

  • openidm.script.javascript.sources

  • openidm.ssl.host.aliases

  • com.iplanet.am.cookie.name

  • com.sun.identity.auth.cookieName

Changes to logging.properties

The default log message formatter has changed from ThreadIdLogFormatter to SanitizedThreadIdLogFormatter. The new default encodes control characters (such as newline characters) using URL-encoding, to protect against log forgery. Control characters in stack traces are not encoded. Learn more in Log message format.

Change to how authorization roles are assigned

In previous IDM releases, managed users were granted the openidm-authorized role as a relationship during user creation as part of the onCreateUser.js script. In IDM 7, users are granted the openidm-authorized role statically when they authenticate. Learn more in Authentication and roles.

This way of granting internal authentication roles is considered a best practice and is recommended for performance reasons. However, if your deployment relies on the old way of granting the openidm-authorized role, that configuration is still supported, and you can use your existing onCreateUser.js script to grant the role on creation.

Schema change to authzRoles

The default relationship model for authzRoles and authzMembers has changed in this release. In the default configuration, a user’s authzRoles now references only the internal/role resource collection and not the managed/role. Conversely, an internal role’s authzMembers property now references only the managed/user resource collection.

The default schema configuration files have been amended to support this change. The managed/role collection has been removed from the authzRoles property on a managed user object and the internal/user collection has been removed from the authzMembers property on an internal role object.

Multiple resource collections for a single relationship field are not currently supported with a DS repository. For legacy reasons, Multiple resource collections will still work with a JDBC repository.

Change to the INTERNAL_USER authentication module

The INTERNAL_USER authentication module is no longer provided in the default authentication configuration.

This change means that any scripts you used previously to update internal user passwords in the IDM repository will need to be modified.

Change to Prometheus monitoring

Monitoring using Prometheus is no longer achieved with a specific access role. The openidm/metrics/prometheus endpoint is now protected by a basic authentication filter, using credentials set in the resolver/boot.properties file. Learn more in Prometheus endpoint.

Change in how boolean values are assessed

Properties stored in the repository with boolean (true/false) values are processed differently from this release. A property value is now considered false if its value is false or null. The value is considered true only if it is true, not if it is null. If you are migrating from a previous IDM release, you might need to adjust your scripts to take this change into account.

Queued sync changes

Processing order of queued synchronization mappings

In previous IDM releases, mappings for which queued synchronization was enabled were processed first. The synchronization engine would then process the non-queued mappings in order. In IDM 7, all mappings are processed in the order in which they are listed, regardless of whether queued synchronization is enabled.

If you want to retain the pre-7.0 behavior, place your queued synchronization mappings first in your list of mappings.

Removal of remainingRetries from queued synchronization

This release lets you configure an infinite number of queued synchronization retries. As part of this change, the remainingRetries property has been removed from the queued synchronization object.

Learn more in Configure queued synchronization.

Virtual property calculation for effectiveRoles and effectiveAssignments

effectiveRoles and effectiveAssignments are now calculated in IDM by default, using the new queryConfig property. The old method of using onRetrieve scripts will still work. The new queryConfig property is also available for use with other virtual properties. Learn more in Effective roles and effective assignments and Virtual properties.

Gzip compression for HTTP responses

You can now configure Gzip compression for HTTP responses in conf/jetty.xml. In previous IDM releases, compression was configured in conf/servletfilter-gzip.json. This file has been removed.

Configurable hashing

IDM 7 supports configurable hashing algorithms.

Temporal constraint enforcement on roles

Enforcing temporal constraints on roles is now achieved through Java, rather than through the onSync-roles.js and postOperation-roles.js scripts. These scripts are still provided in openidm/bin/defaults/script/roles for backward compatibility.

To use the new Java-based functionality in existing deployments, change the role object in your managed object schema (conf/managed.json) by adding "isTemporalConstraint" : true to the "temporalConstraints" object. For example:

"temporalConstraints" : {
    "description" : "An array of temporal constraints for a role",
    "title" : "Temporal Constraints",
    "viewable" : false,
    "returnByDefault" : true,
    "isTemporalConstraint" : true,
    "type" : "array",
    ...
}

Learn more in Use temporal constraints to restrict effective roles.

Change to JMS audit handler

The batch configuration for the JMS common audit handler for access logs has changed to support reconnection if the broker becomes unavailable.

This change adds a batch.writeInterval setting. It removes the following settings:

  • batch.batchEnabled

  • batch.insertTimeoutSec

  • batch.pollTimeoutSec

  • batch.shutdownTimeoutSec

  • batch.threadCount

Learn more in Configure the JMS audit event handler.

Change to default audit configuration

The default audit configuration no longer includes the recon audit topic. You can enable it by adding the recon audit topic to the topics list in conf/audit.json for the event handlers you choose.

This change does not affect how auditing reconciliations works, just what the default configuration includes. No action is necessary unless you wish to have auditing on reconciliations enabled on a new installation. Learn more in Query the reconciliation audit log.

Datatype of userPassword property in provisioner files

As a security precaution, the nativeType for userPassword properties has been changed to JAVA_TYPE_GUARDEDSTRING in all sample provisioner files for the LDAP connector. If you have customized provisioner files, you should change this property. For example, change:

Example provisioner update

  • BEFORE

  • AFTER

"userPassword" : {
    "type" : "string",
    "nativeName" : "userPassword",
    "nativeType" : "string",
    ...
"userPassword" : {
    "type" : "string",
    "nativeName" : "__PASSWORD__",
    "nativeType" : "JAVA_TYPE_GUARDEDSTRING",
    ...

Previous IDM versions included a global consent setting in conf/consent.json. This file included a single configuration property, enabled, which determined whether IDM should check any mappings where consent was enabled and prompt end users for consent.

This global consent setting and the corresponding consent.json file have been removed. If you have an existing consent.json file in your configuration, it will be ignored.

Consent is now assessed only on a per-mapping, per-object basis.

Support for MySQL Connector/J version 8.0

IDM 7 adds support for the latest version of MySQL Connector/J. If you are using MySQL Connector/J version 8.0 or later, make sure your datasource.jdbc-default.json file includes a setting for the time zone in your jdbcUrl property:

"jdbcUrl" : "jdbc:mysql://&{openidm.repo.host}:&{openidm.repo.port}/openidm?allowMultiQueries=true&characterEncoding=utf8&serverTimezone=UTC",

Also, note the driverClass changed in MySQL Connector/J version 8.0, from com.mysql.jdbc.Driver to com.mysql.cj.jdbc.Driver. The previous driverClass name will still work for now, but should be updated to avoid it displaying a warning when starting up IDM.

Default security protocols for inbound connections

The default security protocols for inbound connections to IDM are TLSv1.2 and TLSv1.3. Learn more in Jetty property reference.

Support for the TLSv1.1 protocol has been removed by default.

Removal of address2 from the managed object schema

The address2 attribute has been removed from the managed object schema (conf/managed.json).

ICF and connector changes

The following ICF and connector changes will have an impact on existing IDM deployments that use those connectors:

Workday connector

The Workday connector is no longer bundled with IDM. Download the connector and its dependencies from the Backstage download site.

Database Table connector

The configuration requirements for the Database Table connector have changed:

  • The jdbcDriver and jdbcUrlTemplate properties have been removed. Use driverClassName and url instead.

  • The database property has been removed. The database should now be specified in the JDBC address in url.

  • Additional (optional) configuration properties are now available. For a full list, refer to Database table connector.

Additionally, the Database Table connector example configurations have changed:

samples/example-configurations/provisioners/provisioner.openicf-contractordb.json

  • Removed required : true from the __NAME__ property.

  • Added required : true to the EMAIL property.

  • Removed "keyColumn" : "UNIQUE_ID".

samples/example-configurations/provisioners/provisioner.openicf-contractordb.sql

Set EMAIL as the PRIMARY KEY.

Archive

For documentation and release information prior to IDM 7.0, check out the Documentation Archive.