Notes covering ForgeRock® Identity Management software requirements, fixes, and known issues. This software offers flexible services for automating management of the identity life cycle.

About ForgeRock Identity Management Software

ForgeRock Identity Platform™ serves as the basis for our simple and comprehensive Identity and Access Management solution. We help our customers deepen their relationships with their customers, and improve the productivity and connectivity of their employees and partners. For more information about ForgeRock and about the platform, see https://www.forgerock.com.

The ForgeRock Common REST API works across the platform to provide common ways to access web resources and collections of resources.

ForgeRock Identity Management software provides centralized, simple management and synchronization of identities for users, devices and things.

ForgeRock Identity Management software is highly flexible and therefore able to fit almost any use case and workflow.

These release notes are written for anyone using the ForgeRock Identity Management 6.5 release. Read these notes before you install or upgrade ForgeRock Identity Management software.

These release notes cover the following topics:

  • A list of the major new features and functionality provided with this release

  • Hardware and software prerequisites for installing and upgrading ForgeRock Identity Management software

  • Compatibility with previous releases

  • Potential upcoming deprecation and removals that affect scripts and applications

  • Issues fixed since the previous release

  • Known issues open at the time of release

For installation instructions, see "Preparing to Install and Run Servers" in the Installation Guide.

Several samples are provided to familiarize you with the IDM features. For more information, see "Overview of the Samples" in the Samples Guide.

For an architectural overview and a high-level presentation of IDM, see "Architectural Overview" in the Integrator's Guide.

Chapter 1. What's New

This chapter covers new capabilities in ForgeRock Identity Management 6.5.0.

1.1. New Features

This release of ForgeRock Identity Management software includes the following new features:

Delegated Administration Capabilities

IDM 6.5.0 supports delegated administration, through a privilege model. For more information, see "Privileges and Delegation" in the Integrator's Guide.

New End User UI

IDM 6.5.0 includes an End User UI based on the Vue JavaScript framework. To facilitate customization, ForgeRock has made the End User UI code available in the following public Git repository: Identity Management (End User) - UI .

You can customize the default End User UI, and create your own End User UIs, based on the code in this Git repository.

Only one registration flow is provided by default. You can set up separate registration flows for different sets of users (such as employees and contractors), as described in "Configuring Multiple User Self-Registration Flows" in the Integrator's Guide.

Keystores and Truststores now configured through the Secrets Service

The configuration keystores and truststores are now managed by a new IDM secrets service. You can modify secrets through the secrets.json file in your project's conf/ subdirectory. The secrets service also supports key rotation, which means the active key may not be what's used to decrypt information.

In addition, each alias in secrets.json now has a dedicated capability and function. For more information, see "Accessing IDM Keys and Certificates" in the Integrator's Guide.

Oracle Database Universal Connection Pool (Oracle UCP)

IDM now supports Oracle UCP as an alternative to the default HikariCP connection pool library, solely for an Oracle DB. For more information, see "Setting Up an Oracle DB Repository" in the Installation Guide.

JSON Standard Output Audit Event Handler

IDM now supports sending log messages to standard output in the OSGi console.

For details, see "JSON Standard Output Audit Event Handler" in the Integrator's Guide.

New Notification Service

IDM now includes a dedicated customizable notification service that sends messages as configured. Notifications are no longer configured in the onUpdateUser.js script, but are shown in dedicated notification-*.json files. For more information, see "Configuring Notifications" in the Integrator's Guide.

New HubSpot Connector and Sample

IDM 6.5.0 supports a new HubSpot connector, available from the ForgeRock BackStage download site:

For more information, see "HubSpot Connector" in the Connector Reference. To help you get started with this connector, see "Synchronizing Data Between IDM and HubSpot" in the Samples Guide.

1.2. Product Improvements

This release of Identity Management software includes the following enhancements:

.NET Connector Server Now Uses WCF by Default

On Windows 10, 2012, and 2016, the .NET connector server now uses Windows Communication Foundation (WCF) as the default WebSockets library, instead of Vtortola. Vtortola is still the default library on Windows 2008.

Synchronization Performance Improvements

IDM now supports asynchronous (queued) synchronization for implicit synchronization operations. For more information, see "Queued Synchronization" in the Integrator's Guide.

Improved Connectors and Samples

The Salesforce Connector has been rewritten as a standard ICF connector, rather than a separate IDM module. For more information, see "Salesforce Connector" in the Connector Reference.

The SCIM sample (samples/sync-with-scim/) has been revised. For more information, see "Synchronizing Data Between IDM and a SCIM Provider" in the Samples Guide.

Java Support

IDM software now supports Java 8 and Java 11.

Ability to Encrypt/Decrypt via REST

You can now use the ?_action=eval option on the script endpoint. For more information, see "Encrypting and Decrypting Information" in the Integrator's Guide.

1.3. Security Advisories

ForgeRock issues security advisories in collaboration with our customers and the open source community to address any security vulnerabilities transparently and rapidly. ForgeRock's security advisory policy governs the process on how security issues are submitted, received, and evaluated as well as the timeline for the issuance of security advisories and patches.

For details of all the security advisories across ForgeRock products, see Security Advisories in the Knowledge Base library.

Chapter 2. Before You Install

This chapter covers requirements to consider before you run ForgeRock Identity Management software, especially before you run the software in your production environment.

If you have a special request to support a component or combination not listed here, contact ForgeRock at info@forgerock.com.

2.1. Supported Repositories

The following repositories are supported for use in production:

  • ForgeRock Directory Services (DS) 6.5

    By default, IDM uses an embedded DS instance for testing purposes. The embedded instance is not supported in production. If you want to use DS as a repository in production, you must set up an external instance.

  • MySQL version 5.6 and 5.7 with MySQL JDBC Driver Connector/J 5.1.18 or later

  • MariaDB version 10.0, 10.1, and 10.2 with MySQL JDBC Driver Connector/J 5.1.18 or later

  • Microsoft SQL Server 2012, 2014, and 2016

  • Oracle Database 11gR2, 12c, 12c Release 1 (12.1), and 12c Release 2 (12.2)

  • PostgreSQL 9.3.10, 9.4.5, 9.6, and 10

  • IBM DB2, 10.1, 10.5, 11

Note

These repositories may not be supported on all operating system platforms. See documentation from repository owners for more information.

Do not mix and match versions. For example, if you're running Oracle Database 11gR2, and want to take advantage of the new support for Oracle UCP, download driver and companion JARs for Oracle version 11gR2.

2.2. Containers

You must install IDM as a stand-alone service, using Apache Felix and Jetty, as provided. Alternate containers are not supported.

IDM bundles Jetty version 9.2.

2.3. Supported Connectors

IDM bundles the following connectors:

  • Adobe CM Connector

  • CSV File Connector

  • Database Table Connector

  • Google Apps Connector

  • Groovy Connector Toolkit

    This toolkit enables you to create scripted connectors to virtually any resource.

  • Kerberos Connector

  • LDAP Connector

  • Marketo Connector

  • MongoDB Connector

  • Salesforce Connector

  • SCIM Connector

  • Scripted CREST Connector

  • Scripted REST Connector

  • Scripted SQL Connector

  • ServiceNow Connector

  • Scripted SSH Connector

    Currently supported only as a prerequisite for the Kerberos Connector

  • Workday Connector

A PowerShell Connector Toolkit is available for download from the ForgeRock BackStage download site. This Toolkit enables you to create scripted connectors to address the requirements of your Microsoft Windows ecosystem.

Additional connectors are available from the ForgeRock BackStage download site.

Use of the LDAP connector to provision to Active Directory is supported with Active Directory Domain Controllers, Active Directory Global Catalogues, and Active Directory Lightweight Directory Services (LDS).

Windows versions 2008, 2012 R2, and 2016 are supported as the remote systems for connectors and password synchronization plugins.

You must use the supported versions of the .NET Connector Server, or the Java Connector Server. The 1.5.x Java Connector Server is backward compatible with the version 1.1.x connectors. The 1.5.x .NET Connector Server is compatible only with the 1.4.x and 1.5.x connectors. For more information, see "IDM / ICF Compatibility Matrix".

The Java connector server requires Java 8 or Java 11 and is supported on any platform on which Java runs.

The .NET connector server requires the .NET framework (version 4.5 or later) and is supported on Windows Server versions 2008 R2, 2012 R2 and 2016.

Important

Although the scripted connector toolkits are supported, connectors that you build with these toolkits are not supported. You can find examples of how to build connectors with these toolkits in the Samples Guide.

The following table lists the connector and connector server versions that are supported across IDM versions. For a list of connectors supported with this IDM release, see "Connector Overview" in the Connector Reference.

IDM / ICF Compatibility Matrix
IDM VersionICF FrameworkSupported Java ConnectorsSupported .NET Connectors
3.x1.4.x, 1.5.xJava connectors version 1.1.x - 1.5.x Active Directory Connector 1.4.0.0, PowerShell Connector 1.4.x

Note that the Active Directory connector is deprecated. For more information, see "Active Directory Connector" in the Connector Reference

4.x1.4.x, 1.5.xJava connectors version 1.1.x - 1.5.x Active Directory Connector 1.4.0.0, PowerShell Connector 1.4.x

Note that the Active Directory connector is deprecated. For more information, see "Active Directory Connector" in the Connector Reference

5.x1.4.x, 1.5.xJava connectors version 1.1.x - 1.5.x Active Directory Connector 1.4.0.0, PowerShell Connector 1.4.x

Note that the Active Directory connector is deprecated. For more information, see "Active Directory Connector" in the Connector Reference

6.x1.4.x, 1.5.xJava connectors version 1.1.x - 1.5.x PowerShell Connector 1.4.x

The following table lists the supported password synchronization plugins:

Supported Password Synchronization Plugins
PluginSupported Version
DS Password Synchronization Plugin

6.5.0, supported with DS 6.5.0

6.0.0, supported with DS 6.0.0

5.5.0, supported with DS 5.5.0

5.0.0, supported with DS 5.0.0

3.5.0, supported with OpenDJ 3.5.0

DS Password Sync plugins are not supported with DS OEM

Active Directory Password Synchronization Plugin1.3.0, 1.2.0 and 1.1.0 supported on Windows 2008 R2, Windows 2012 R2 and Windows 2016

2.4. Choosing a Browser

ForgeRock has tested many browsers with the IDM UI, including the following browsers:

  • Chrome and Chromium, latest stable version

  • Firefox, latest stable version

  • Safari, latest stable version

  • Internet Explorer 11 and later

2.5. Choosing an Operating System

IDM is supported on the following operating systems:

  • Red Hat Enterprise Linux (and CentOS Linux) 6.5 and later, 7.x

  • Ubuntu Linux 16.04

  • Windows 2008 R2, 2012 R2, 2016

2.6. Preparing the Java Environment

IDM requires Java 8 or Java 11, specifically at least the Java Standard Edition runtime environment.

ForgeRock validates IDM software with Oracle JDK and OpenJDK, and does occasionally run sanity tests with other JDKs. Support for very specific Java and hardware combinations is best-effort. This means that if you encounter an issue when using a particular JVM/hardware combination, you must also demonstrate the problem on a system that is widespread and easily tested by any member of the community.

ForgeRock recommends that you keep your Java installation up to date with the latest security fixes.

Important

  • The clock implementation in JDK 8 is based on System.currentTimeMillis() and supports time resolution up to the millisecond only. JDK 11 has an enhanced system clock implementation that provides at least the same precision as the underlying system clock.

    Precise time resolution is important for features such as queued synchronization that rely on precise time for ordering of operations. It is therefore recommended that you use JDK 11 for optimum performance of these features.

  • If you are using Oracle JDK 8 and you use 2048-bit SSL certificates, you must install the Unlimited JCE policy to enable IDM to use those certificates.

    Download and install the Unlimited JCE Policy for Java 8 from the Oracle Technetwork site. Unzip the JCE zip file and install the JCE policy JAR files in the /lib/security folder of the JRE.

2.7. Fulfilling Memory and Disk Space Requirements

When you install IDM for evaluation, with the embedded DS repository, you need 256 MB memory (32-bit) or 1 GB memory (64-bit) available.

You also need 10 GB free disk space for the software and for sample data.

Important

A DS repository (whether embedded or external) requires free disk space of 5% of the filesystem size, plus 1 GB by default. To change this requirement, set the disk-full-threshold in the DS configuration. For more information, see Setting Disk Space Thresholds For Database Backends in the DS Administration Guide.

In the case of an embedded DS instance, you can manage the configuration using the dsconfig command in /path/to/openidm/db/openidm/opendj/bin.

In production, disk space and memory requirements will depend on the size of your external repository, as well as the size of the audit and service log files that IDM creates.

The amount of memory that IDM consumes is highly dependent on the data that it holds. Queries that return large data sets will have a significant impact on heap requirements, particularly if they are run in parallel with other large data requests. To avoid out of memory errors, analyze your data requirements, set the heap configuration appropriately, and modify access controls to restrict requests on large data sets.

Chapter 3. Fixes, Limitations, and Known Issues

This chapter covers the status of key issues and limitations for ForgeRock Identity Management 6.5.0. For details and information on other issues, see the IDM issue tracker.

3.1. Fixed Issues

The following important bugs were fixed in this release:

  • OPENIDM-10542: IDM decryption fails with AES 256-bit key

  • OPENIDM-11292: Registration autologin with full-stack not working

  • OPENIDM-9665: Startup of OpenIDM with MySQL repo ends in ACTIVE_READY state even if repo-jdbc bundle fails to initialize

  • OPENIDM-11602: Recons failing due to memory issues via the scripted sql connector

  • OPENIDM-11480: With Oracle repo, Create or Update Managed user via UI results in 500 error

  • OPENIDM-6514: JDBC repo errors on startup when using mysql

  • OPENIDM-10132: IDM does not start, when configured with HSM and Embedded DS

  • OPENIDM-9446: Random startup failures when using DB2 as a repo

  • OPENIDM-9520: Update via REST with PUT removes private fields which are not included in the request

  • OPENIDM-9331: Enabling CSV tamper prevention through the Admin UI may fail with a keystore password error

  • OPENIDM-10600: Internal error "no deployed process definition found" after deleting process definition

  • OPENIDM-5465: Performance Issue updating conditional role memberships

  • OPENIDM-7665: Admin UI mapping view returns HTTP 400 error

  • OPENIDM-10653: Password reset fails using explicit tables

  • OPENIDM-9576: Records with missing _sortKeys are not returned in query results

  • OPENIDM-8043: Unable to initialize keystore and truststore when passwords are different

  • OPENIDM-10720: If a user does not exist in the workflow identity service there will be an NPE when trying to retrieve that user

  • OPENIDM-10793: Problems with propvalue column size in properties tables

  • OPENIDM-11052: Admin UI Mappings page load delay on system?_action=test REST call

  • OPENIDM-11597: IllegalArgumentException updating external account if trace is enabled

  • OPENIDM-10948: OpenerHandler require does not work with Internet Explorer

  • OPENIDM-10919: JavaScript in Internet Explorer does not support the "includes" method of String

  • OPENIDM-11863: Default configuration for jsonstore.json is incorrect

  • OPENIDM-10603: Unexpected "manager" property in the "before" of activity audit records when patching manager on a user

  • OPENIDM-11055: In some Full Stack configurations, you might need to increase the default header size

  • OPENIDM-11237: The `openidm.workflow.enabled` property does not affect workflows

  • OPENIDM-10749: Require modules appear to be reloaded with every script reference

  • OPENIDM-10321: Salesforce provisioner fails to activate and throws NPEs at runtime

  • OPENIDM-10787: The javascript.recompile.minimumInterval config values incorrect for common-js modules

  • OPENIDM-10974: openidm.objecttypes.objecttype definition not consistent across DBs

  • OPENIDM-11510: UI: Can't edit properties of newly added object type in connector configuration

  • OPENIDM-11024: NPE can be thrown if the authentication service comes up before the identityService

  • OPENIDM-10263: Salesforce connector error while accessing data from User and Profile objects

  • OPENIDM-11822: migrateRepoRelationshipsData.js script does not set relationships correctly for >1000 relations

  • OPENIDM-10828: MongoDB Connector UI configuration has an incorrect documentation link

  • OPENIDM-11215: IDM hangs using IE11 with error "Promise is undefined" in ResourceQueryFilterEditor.js

  • OPENIDM-10823: UI intermittently doesn't work with a changed REST context when using Firefox

  • OPENIDM-11862: Setting a timeout on a uuid token via jsonstore.json has no effect

  • OPENIDM-11739: Concurrent recons could cause exception deleting interim state instance deleteInterimStateInstance

  • OPENIDM-11737: Missing relationship references when link expanding on missing resourceCollection in schema

  • OPENIDM-11810: When generating full config, "id": "FIX_ME" is returned under operationOptions

  • OPENIDM-10833: Cluster widget doesn't show shutdown time for killed node correctly

  • OPENIDM-11235: Recon shows error "Target does not support attribute lastSync"

  • OPENIDM-11174: Unable to resume scheduler jobs after successful pause

  • OPENIDM-11852: Clustered recon in a multi-node environment may never complete

  • OPENIDM-10740: Sharing and Activity (UMA) sections in the Self-Service UI do not display thumbnails

  • OPENIDM-10400: When configuring a new LDAP Connector config for AD using the Admin UI, the groupMembership, groupType, and groupScope attributes in the user schema are not set up properly

  • OPENIDM-10867: Email password string property substitution is not displayed in UI

  • OPENIDM-11554: Health service does not identify ds repo bundle correctly

  • OPENIDM-11231: IDM logs has suspicious INFO message in clustered recon

  • OPENIDM-10578: Unable to specify the authenticationId within augmentSecurityContext script

  • OPENIDM-11511: Changing the name of an object type in connector config creates erroneous entries

  • OPENIDM-11667: If Salesforce is unavailable, testing the Salesforce Connector throws a 500 error

  • OPENIDM-11704: UI: Can't edit validation policy without specifying a parameter

  • OPENIDM-10758: openidm.read() returns different content if called from managed.json action or a custom endpoint

  • OPENIDM-10829: PUT modifications to workflow/taskInstance/[_id] return 'Task updated' even when no changes occur

  • OPENIDM-11393: assigning a userTask to openidm-admin could cause null pointer exception

  • OPENIDM-10537: Deleting a previously set field during profile completion does not work

  • OPENIDM-11640: null exception in defaultMappings.json

3.2. Limitations

ForgeRock Identity Management 6.5.0 has the following known limitations:

  • When you add or edit a connector through the Admin UI, the list of required Base Connector Details is not necessarily accurate for your deployment. Some of these details might be required for specific deployment scenarios only. If you need a connector configuration where not all the Base Connector Details are required, you must create your connector configuration file over REST or by editing the provisioner file. For more information, see "Configuring Connectors" in the Integrator's Guide.

  • For OracleDB repositories, queries that use the queryFilter syntax do not work on CLOB columns in explicit tables.

  • A conditional GET request, with the If-Match request header, is not currently supported.

  • IDM provides an embedded workflow and business process engine based on Activiti and the Business Process Model and Notation (BPMN) 2.0 standard. As an embedded system, local integration is supported. Remote integration is not currently supported.

  • When using privileges, relationships are not returned in queries. This means information that is handled as a relationship to another object (such as roles for a managed user) will not be available.

3.3. Known Issues

The following important issues remained open at the time of this release:

  • OPENIDM-12177: Notifications service does not work with relationship fields

  • OPENIDM-12170: Delete on managed or internal object does not return the included relationship fields that were included in the request

  • OPENIDM-12109: Able to add managed object property with illegal character via Admin UI

  • OPENIDM-12106: Delegated Admin query filter and fields requests does not work properly with object type

  • OPENIDM-12105: Delegated Admin UI Should Only Display Supported Fields in grid

  • OPENIDM-12100: An existing privilege should default new schema fields to READ

  • OPENIDM-12078: You cannot customize the aliases of the default keys added to the IDM keystore and truststore

    Workaround: To generate the default keys and certificates with custom aliases, see "To Generate Keys and Certificates With Custom Aliases (Workaround for OPENIDM-12078)".

  • OPENIDM-12077: UI has JSON type pulldown for _rev for internal users

  • OPENIDM-12074: Authentication Provider does not work after restarting IDM and AM

    Workaround: If you have shut down IDM and AM, start AM first. When you can log in, start IDM then navigate to the IDM Admin UI.

  • OPENIDM-12063: Repo init service fails in audit-jdbc sample

  • OPENIDM-12060: Sync triggers can get stuck after nodes are recycled

  • OPENIDM-12017: IDM CAUD syslog product name (APP-NAME) is null

  • OPENIDM-11960: Complex query expressions are not correctly parsed to SOQL for Salesforce

  • OPENIDM-11950: Infinite loop possible for Managed PATCH operations

  • OPENIDM-11921: Errors logged when password-reset email URL is expired and clicked

  • OPENIDM-11879: Workflow time zone handling is not consistent and leads to unexpected results

  • OPENIDM-11765: Warnings on startup when using embedded DS repo with Java 11

  • OPENIDM-11714: Full Stack: /admin endpoint redirects to self-service page

  • OPENIDM-11536: Cannot set user password for user created through full-stack social registration

  • OPENIDM-11408: Paging is not working in 'Association/Data Association Management for mapping detail'.

    Workaround: The JSON audit handler does not support paging. If you use an audit audit handler that supports paging (such as the repository or elasticsearch handlers), you will not encounter this issue.

  • OPENIDM-11370: Activiti workflow mail task goes to default localhost:25

  • OPENIDM-10761: Progressive Profiling scripted condition does not include user fields within "object" map

  • OPENIDM-10660: User metadata is logged in the audit log when an object is changed

  • OPENIDM-10455: Query and non-read operations not authorised for openidm-admin role with OAuth

  • OPENIDM-10072: Scheduler service registered too early by OSGi

  • OPENIDM-9791: Error while generating process diagram, image will not be stored in repository

  • OPENIDM-9554: Workflow Processes Completed have "Not Found Error" for managed/user

  • OPENIDM-9353: IDM does not audit the http response headers in the access audit log

  • OPENIDM-9081: WARNING about extensions directory not existing appears in felix console upon restart of IDM

  • OPENIDM-8518: Not Found error when accessing a process instance via Admin UI

  • OPENIDM-8295: Non-required single relationship properties should be nullable

  • OPENIDM-8122: OpenIDM Cluster incorrectly shows ready and running

  • OPENIDM-8052: Cannot create a remote (.NET) connector through the UI

  • OPENIDM-6467: syslog audit event handler created although required property not set

  • OPENIDM-4149: availableConnectors are not updated after remote ICF shut down

  • OPENIDM-4068: Config Changes made in config files should get logged by the Config Audit Logger.

To Generate Keys and Certificates With Custom Aliases (Workaround for OPENIDM-12078)
  1. Generate each default key with the custom alias, for example:

    keytool -genseckey \
     -alias openidm-sym-default-custom \
     -keyalg AES \
     -keysize 128 \
     -keystore security/keystore.jceks \
     -storetype JCEKS
    
     keytool -genseckey \
      -alias openidm-selfservice-key-custom \
      -keyalg AES \
      -keysize 128 \
      -keystore security/keystore.jceks \
      -storetype JCEKS
    
      keytool -genseckey \
     -alias openidm-jwtsessionhmac-key-custom \
     -keyalg HmacSHA256 \
     -keysize 2048 \
     -keystore security/keystore.jceks \
     -storetype JCEKS
    
     keytool -genkey \
     -alias openidm-localhost-custom \
     -keyalg RSA \
     -keysize 2048 \
     -keystore security/keystore.jceks \
     -storetype JCEKS
    
     keytool -genkey \
     -alias server-cert \
     -keyalg RSA \
     -keysize 2048 \
     -keystore security/keystore.jceks \
     -storetype JCEKS
    
     keytool -genkey \
     -alias selfservice-custom \
     -keyalg RSA \
     -keysize 2048 \
     -keystore security/keystore.jceks \
     -storetype JCEKS
    
     keytool -export \
     -alias openidm-localhost-custom \
     -file exportedCert \
     -keystore security/keystore.jceks \
     -storetype JCEKS
    
     keytool -import \
     -alias openidm-localhost-custom \
     -file exportedCert \
     -keystore security/truststore \
    -storetype JKS

    Note that these commands do not change the alias of the default server-cert. To customize the server-cert alias for an embedded DS repository, define the custom alias in the resolver/boot.properties file, for example "openidm.config.crypto.opendj.localhost.cert=my-custom-alias".

  2. Edit the aliases that are defined in conf/secrets.json. For example, with the aliases specified previously:

    {
      "stores": [
        {
          "name": "mainKeyStore",
          "class": "org.forgerock.openidm.secrets.config.FileBasedStore",
          "config": {
            "file": "&{openidm.keystore.location|&{idm.install.dir}/security/keystore.jceks}",
            "storetype": "&{openidm.keystore.type|JCEKS}",
            "providerName": "&{openidm.keystore.provider|SunJCE}",
            "storePassword": "&{openidm.keystore.password|changeit}",
            "mappings": [
              {
                "secretId" : "idm.default",
                "types": [ "ENCRYPT", "DECRYPT" ],
                "aliases": [ "openidm-sym-default-custom" ]
              },
              {
                "secretId" : "idm.config.encryption",
                "types": [ "ENCRYPT", "DECRYPT" ],
                "aliases": [ "openidm-sym-default-custom" ]
              },
              {
                "secretId" : "idm.password.encryption",
                "types": [ "ENCRYPT", "DECRYPT" ],
                "aliases": [ "openidm-sym-default-custom" ]
              },
              {
                "secretId" : "idm.jwt.session.module.encryption",
                "types": [ "ENCRYPT", "DECRYPT" ],
                "aliases": [ "openidm-localhost-custom" ]
              },
              {
                "secretId" : "idm.jwt.session.module.signing",
                "types": [ "SIGN", "VERIFY" ],
                "aliases": [ "openidm-jwtsessionhmac-key-custom" ]
              },
              {
                "secretId" : "idm.selfservice.encryption",
                "types": [ "ENCRYPT", "DECRYPT" ],
                "aliases": [ "selfservice-custom" ]
              },
              {
                "secretId" : "idm.selfservice.signing",
                "types": [ "SIGN", "VERIFY" ],
                "aliases": [ "openidm-selfservice-key-custom" ]
              }
            ]
          }
        },
        {
          "name": "mainTrustStore",
          "class": "org.forgerock.openidm.secrets.config.FileBasedStore",
          "config": {
            "file": "&{openidm.truststore.location|&{idm.install.dir}/security/truststore}",
            "storetype": "&{openidm.truststore.type|JKS}",
            "providerName": "&{openidm.truststore.provider|SUN}",
            "storePassword": "&{openidm.truststore.password|changeit}",
            "mappings": [
            ]
          }
        }
      ],
      "populateDefaults": false
    }

Chapter 4. Compatibility

This chapter covers major and minor changes to existing functionality, as well as deprecated and removed functionality. You must read this chapter before you start a migration from a previous release.

4.1. Important Changes to Existing Functionality

Take the following changes into account when you update to IDM 6.5.0. These changes will have an impact on existing deployments. Adjust existing scripts and clients accordingly:

No automated update process

The automated update process available with previous IDM versions is no longer supported. Updating servers is now a manual process and is described in detail in "Updating Servers" in the Installation Guide.

Endpoint change from repo/internal to internal

Internal objects previously accessible at the repo/internal/ endpoint are now accessible at the internal/ endpoint. For example, internal user objects are now accessible at internal/user rather than repo/internal/user.

Note

Because this is a breaking change, additional steps are necessary when upgrading from previous versions of IDM. For more information, see "Changes to repo/internal".

Roles are now referred to by full path

Internal and managed roles are now referenced by their full path (for example, openidm-authorized is now internal/role/openidm-authorized). Support for using role names without a full path is deprecated, and may be removed in a later release.

DS repositories now return a null value for missing properties

Previously, embedded and external repo.ds.json files defaulted to not returning empty properties. They now return the empty properties with a value of null. This aligns more closely with the behavior seen in JDBC repositories that use explicit mappings.

If you wish to revert this behavior, change returnNullForMissingProperties to false in the rest2LdapOptions property in your repo.ds.json file. For more information about the returnNullForMissingProperties property, see Gateway REST2LDAP Configuration File in the DS Reference.

End user notification configuration files have changed

End user notifications are now configured in notification-*.json files. To review the defaults, see "Notification Configuration Files" in the Integrator's Guide.

Notification configuration options have been removed from onUpdateUser.js.

In addition, the following files have been removed for IDM 6.5.0:

  • userNotifications.js

  • onDelete-user-cleanup.js

Change to proxy configuration for external REST service

In previous releases, configuring a proxy for the external REST service was achieved by setting the proxySystem property in the external.rest.json configuration file. There is now a system-wide HTTP client configuration that includes proxy settings. For more information, see "Configuring HTTP Clients" in the Integrator's Guide.

4.2. ICF and Connector Changes

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

Improvements to the Scripted Groovy Connectors

Connectors based on the Groovy Connector toolkit now use the CachingSimpleTemplateEngine utility class, instead of the SimpleTemplateEngine class.

The SimpleTemplateEngine class is prone to memory leaks. If you have existing Groovy search scripts that use templates, you should update them to use the new class. For example, change:

import groovy.text.SimpleTemplateEngine

to

import org.forgerock.openicf.connectors.groovy.CachingSimpleTemplateEngine

in your SearchScript.groovy scripts.

Removed Azure AD Sample Scripts

The PowerShell Azure AD sample scripts and corresponding sample have been removed from the IDM product. These scripts used a deprecated Powershell Module and may be revised in a future IDM release.

4.3. Deprecated Functionality

This section lists deprecated functionality. Deprecation is defined in "ForgeRock Product Interface Stability".

  • The Office 365 connector is deprecated and support for its use with IDM will be removed in a future release.

    Instead of the Office 365 connector, use the PowerShell Connector Toolkit with the Azure AD scripts, available from the ForgeRock BackStage download site.

  • The ability to configure keystores, truststores, obfuscation, and encryption in the IDM 6 version of openidm/resolver/boot.properties file is deprecated and will be removed in a future release.

    The ability to set up encryption with a key alias in the managed.json file has also been deprecated.

    This functionality has been replaced by the secrets service in IDM 6.5. For more information, see "Configuring the Keystore and Truststore" in the Integrator's Guide.

  • Support for the TLSv1.1 protocol has been deprecated and will be removed in a future release. For more information, on the potential vulnerability, see CVE-2011-3389 from the National Vulnerability Database from the US National Institute of Standards and Technology.

    The default security protocol for IDM is TLSv1.2. Do not downgrade this protocol to TLSv1.1 unless necessary. For more information, see "Setting the TLS Version" in the Integrator's Guide.

  • Support for oauthReturn as an endpoint for OAuth2 and OpenID Connect standards has been deprecated for interactions with AM and will be removed in a future release. Support has been removed for interactions with social identity providers, as discussed in "Removed Functionality".

    Default versions of relevant configuration files no longer include oauthReturn in the redirectUri setting. However, for IDM 6.5.0, these configuration files should still work both with and without oauthReturn in the endpoint.

    This change affects any configuration where IDM interacts as a Relying Party with AM as an OpenID Provider. For related documentation, see "Integrating IDM With the ForgeRock Identity Platform" in the Samples Guide

  • In schedule configurations, setting a time zone using the timeZone field is deprecated. To specify a time zone for schedules, use the startTime and endTime fields, as described in "Configuring Schedules" in the Integrator's Guide.

  • Support for the MD5 and SHA-1 hash algorithms is deprecated and will be removed in a future release. You should use more secure algorithms in a production environment. For a list of supported hash algorithms, see "Encoding Attribute Values by Using Salted Hash Algorithms" in the Integrator's Guide.

  • The Active Directory (AD) .NET Connector is deprecated and support for its use in IDM will be removed in a future release.

    For simple Active Directory (and Active Directory LDS) deployments, the Generic LDAP Connector works better than the Active Directory connector, in most circumstances. For more information, see "Generic LDAP Connector" in the Connector Reference.

    For more complex Active Directory deployments, use the PowerShell Connector Toolkit, as described in "PowerShell Connector Toolkit" in the Connector Reference.

    Note that deprecating the AD Connector has no impact on the PowerShell connector, or on the .NET Connector Server.

  • When configuring connectors, (see "Configuring Connectors" in the Integrator's Guide), you can set up nativeType property level extensions. The JAVA_TYPE_DATE extension is deprecated.

  • Support for a POST request with ?_action=patch is deprecated, when patching a specific resource. Support for a POST request with ?_action=patch is retained, when patching by query on a collection.

    Clients that do not support the regular PATCH verb should use the X-HTTP-Method-Override header instead.

    For example, the following POST request uses the X-HTTP-Method-Override header to patch user jdoe's entry:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --header "Content-Type: application/json" \
     --request POST \
     --header "X-HTTP-Method-Override: PATCH" \
     --data '[
        {
        "operation":"replace",
        "field":"/description",
        "value":"The new description for Jdoe"
        }
      ]' \
      "http://localhost:8080/openidm/managed/user/jdoe"

No additional functionality is deprecated at this time.

4.4. Removed Functionality

  • Support for the TLSv1.0 protocol has been removed. For more information, see the following PDF: Migrating from SSL and Early TLS from the PCI Security Standards Council.

    The default security protocol for IDM is TLSv1.2. Do not downgrade this protocol unless you have a specific need.

  • Support for oauthReturn as an endpoint for OAuth2 and OpenID Connect standards has been removed for interactions with social identity providers. It is still available for interactions with AM, as discussed in "Deprecated Functionality".

    Default versions of relevant configuration files no longer include oauthReturn in the redirectUri setting.

    This change affects any configuration where IDM interacts as a Relying Party with a social identity provider as an OAuth2 or an OpenID Connect Provider. For related documentation, see "Configuring Social Identity Providers" in the Integrator's Guide

  • The ability to update IDM through the Admin UI from IDM 6 to IDM 6.5.0 has been removed. At this time, we anticipate that updates to IDM 6.5.0 will still be supported through the CLI.

  • Support for the BoneCP Java database connection (JDBC) pool library has been removed. HikariCP has been the default IDM JDBC pool library since version 5. This affects deployments that use JDBC repositories.

    For more information on the configuration of HikariCP, see "Understanding the JDBC Connection Configuration File" in the Integrator's Guide.

4.5. Functionality That Will Change in the Future

No major functionality is planned to change at this time.

Chapter 5. Updating to IDM 6.5.0

IDM 6.5.0 provides a number of new features that require changes to an existing configuration. These changes can be broken into two categories: changes that are required for IDM to function, and changes that are only required if you wish to make use of these new features. Before performing the changes laid out in this chapter, review the instructions in "Updating Servers" in the Installation Guide.

5.1. Required Changes to IDM

The following changes are required when updating from a previous IDM release:

5.1.1. Database Changes

There have been several changes to the database structure for IDM repositories. Run the following scripts to upgrade your database, which can be found in bin/update/scripts/database-type/:

alter_internalrole.sql or alter_internalrole.ldif

This updates the internalrole table to include several new columns.

alter_objecttypes.sql

Previous MySQL, Oracle, and PostgreSQL database configurations had set the objecttype column of IDM's objecttypes table to NULL. This should be changed to NOT NULL.

Microsoft SQL and DB2 were already configured to be NOT NULL and need no further changes. DS also needs no changes.

alter_relationships.sql

Caution

This script removes a column from the relationships table. We recommend making a backup of your repository prior to running this file.

This removes the properties column from the relationships table. IDM gets relationship properties from the fullobject column, making the properties column unnecessary.

alter_uinotification.sql

This updates the uinotification table to adjust the column length for createDate.

create_indices.sql

(PostgreSQL only) This creates an index for reconid in the genericobjects table, and adds indices for several fields in the clusterobjects table.

migrate_metaobjects.sql

Caution

This script deletes meta data from the genericobjects table after migrating that data to new tables. We recommend making a backup of your repository prior to running this file.

This creates two new tables, metaobjects and metaobjectproperties, then moves user meta data from genericobjects into these two tables.

The number of scripts found in this directory may vary depending on the database you are using. Scripts not listed above are optional, and relate to enabling or configuring specific features in IDM. These will be referenced in the steps for enabling that particular feature in "Enabling New Features in IDM".

5.1.2. Configuration Changes

The following changes to your configuration are required:

5.1.2.1. Changes for the New Secrets Service

The IDM 6 version of boot.properties may not be supported in the next release. Therefore, you should review the differences as described in "Configuration Options in secrets.json" in the Integrator's Guide as soon as possible.

5.1.2.1.1. Secrets Service Updates to boot.properties

When comparing the boot.properties files from IDM 6 and IDM 6.5, you'll note differences based on the new secrets service:

  • Keystore and Truststore information (such as openidm.truststore.type or openidm.keystore.password) are no longer stored in boot.properties. This information has been moved to conf/secrets.json.

  • Cryptographic settings such as openidm.config.crypto.alias have been moved to conf/secrets.json.

5.1.2.1.2. Secrets Service Updates to managed.json

In the IDM 6 version of managed.json file, you'll see the following entry related to user password encryption:

"key" : "openidm-sym-default"

For the IDM 6.5 version of managed.json, this entry has changed to:

"purpose" : "idm.password.encryption"

You can now define idm.password.encryption in the new secrets.json file.

5.1.2.2. Changes to repo/internal

Internal objects are no longer stored in repo/internal, and are now accessed via the internal endpoint. If you are updating from a previous release of IDM, you must update existing references to repo/internal to the new endpoint.

  1. References to repo/internal in existing configuration files need to be changed to internal. The following files must be updated:

    authentication.json

    The authModules of STATIC_USER and INTERNAL_USER need to update their queryOnResource value from repo/internal/user to internal/user.

    managed.json

    The managed user's authzRoles "Internal Role" resource collection should change its path from repo/internal/role to internal/role.

    policy.json

    The resource of repo/internal/user/* should change to internal/user/*.

    router.json

    One filter pattern needs to be updated: (managed|system|repo/internal)($|(/.)) should change to (managed|system|internal)($|(/.).

    One filter pattern needs to be deleted: the repo/internal/user((/.)|$) pattern is no longer required and should be deleted from router.json.

  2. Run the removeRepoPathFromRelationships endpoint. This will update any existing relationships to remove repo/ from internal roles:

    $ curl \
     --header "X-OpenIDM-Username: openidm-admin" \
     --header "X-OpenIDM-Password: openidm-admin" \
     --request GET \
    "http://localhost:8080/openidm/endpoint/removeRepoPathFromRelationships"

    Note

    Prior to running this endpoint, you may need to temporarily adjust access.js to include extra access to endpoints:

    {
        "pattern"    : "endpoint/*",
        "roles"      : "*",
        "methods"    : "read",
        "actions"    : "*"
    },

5.1.2.3. Changes to Internal Roles and Internal Users

There have been updates to the internal schema for internal roles and users, which require updating existing entries in your repository. To update these internal roles and internal users, run the updateInternalUserAndInternalRoleEntries endpoint:

$ curl \
 --header "X-OpenIDM-Username: openidm-admin" \
 --header "X-OpenIDM-Password: openidm-admin" \
 --request GET \
"http://localhost:8080/openidm/endpoint/updateInternalUserAndInternalRoleEntries"

Note

Prior to running this endpoint, you may need to temporarily adjust access.js to include extra access to endpoints:

{
   "pattern"    : "endpoint/*",
   "roles"      : "*",
   "methods"    : "read",
   "actions"    : "*"
},

5.1.2.4. Changes to repo.jdbc.json

The following fields can be removed from existing repo.jdbc.json files when upgrading from a previous version:

  • The properties field of the relationships object has been removed when using generic resource mappings. The object path to this field is /resourceMapping/genericMapping/relationships/properties.

5.1.2.5. Enabling HikariCP

HikariCP is the new default IDM Java database connection (JDBC) pool library. If you are using a JDBC repository, adjust datasource.jdbc-default.json to use hikari instead of boneCP for the connectionPool type:

"connectionPool" : {
    "type" : "hikari",
    ...
}

For more information on configuring HikariCP, see "Understanding the JDBC Connection Configuration File" in the Integrator's Guide.

5.1.2.6. Changes to router.json

5.1.2.6.1. Changes to onRequest Filter

The call to router-authz.js has been modified in the onRequest filter in router.json:

"onRequest" : {
    "type" : "text/javascript",
    "source" : "require('router-authz').testAccess()"
}
5.1.2.6.2. Addition of Relationship Filter

An onResponse filter has been added in router.json, adding filtering around relationships:

{
    "pattern" : "^(managed|internal)($|(/.+))",
    "condition" : {
        "type" : "text/javascript",
        "source" : "context.caller.external === true || context.current.name === 'selfservice'"
    },
    "onResponse" : {
        "type" : "text/javascript",
        "source" : "require('relationshipFilter').filterResponse()"
    }
}
5.1.2.6.3. Changes to Internal User Password Encryption

It is no longer necessary to separately encrypt internal user passwords through an onRequest script in router.json. Internal users will now use the encryption key alias defined in boot.properties.

The following entry in router.json can be safely removed:

{
    "pattern" : "internal/user((/.+)|$)",
    "onRequest" : {
        "type" : "text/javascript",
        "source" : "request.content.password = require('crypto').hash(request.content.password);"
    },
    "methods" : [
        "create",
        "update"
    ]
}

5.1.2.7. Changes to the redirectUri for Social Identity Providers

The value of redirectUri for social identity providers, as configured per "Configuring Social Identity Providers" in the Integrator's Guide has changed.

If you've configured a social identity provider for a previous version of IDM, you'll need to update the redirectUri for the provider, by removing the oauthReturn/ from the URL, in two locations:

identityProvider-name.json

In the configuration file named for the identity provider, such as identityProvider-google.json.

When configuring your identity provider

When you configure your identity provider, look for an entry such as Redirect or Return URL. You'll need to update the value corresponding to the IDM redirectUri on the social identity provider developer (or similar) page.

For example, for IDM 6, you'll have a redirectUri such as:

http://idm.example.com:8080/oauthReturn/

In this case, you'd change the value of redirectUri to:

http://idm.example.com:8080/

5.1.2.8. Changes When Interacting With AM and DS

If you've integrated IDM with AM and DS, as described in "Integrating IDM With the ForgeRock Identity Platform" in the Samples Guide, note the redirectUri in your project's authentication.json file.

For IDM 6.5.0, the redirectUri will have a value like http://idm.example.com:8080/.

For IDM 6, the corresponding redirectUri has a corresponding value of http://idm.example.com:8080/oauthReturn/.

For IDM 6.5.0, you can use either endpoint, as long as you're consistent with the corresponding value described in OAuth 2.0 and OpenID Connect 1.0 Client Settings

5.2. Enabling New Features in IDM

If you are updating from a previous IDM release, read this section and follow the steps required for each feature that you want to enable in the updated deployment.

5.2.1. Enabling Queued Synchronization

IDM now supports queued synchronization, which allows you to queue implicit synchronization activity on actions that would otherwise trigger an immediate implicit synchronization. Several changes are necessary to turn this feature on when updating from a previous version of IDM:

Updating Databases and Configurations for Queued Synchronization
  1. Update your IDM database to add the new syncqueue and locks tables by running either create_syncqueue.sql or create_syncqueue.ldif (depending on your database type), which can be found in bin/update/scripts/database-type/.

  2. Update your repository configuration files to include the new locks and sync/queue mappings in the explicitMapping resource map. For repo.jdbc.json, add:

    "locks" : {
        "table" : "locks",
        "objectToColumn" : {
            "_id" : "objectid",
            "_rev" : "rev",
            "nodeId" : "nodeid"
        }
    },
    "sync/queue" : {
        "table" : "syncqueue",
        "objectToColumn" : {
            "_id" : "objectid",
            "_rev" : "rev",
            "syncAction" : "syncAction",
            "resourceCollection" : "resourceCollection",
            "resourceId" : "resourceId",
            "mapping" : "mapping",
            "objectRev" : "objectRev",
            "oldObject" : {"column" : "oldObject", "type" : "JSON_MAP"},
            "newObject" : {"column" : "newObject", "type" : "JSON_MAP"},
            "context" : {"column" : "context", "type" : "JSON_MAP"},
            "state" : "state",
            "nodeId" : "nodeId",
            "remainingRetries" : {"column" : "remainingRetries", "type" : "NUMBER"},
            "createDate" : "createDate"
        }
    },

    For repo.ds-external.json, add:

    "locks" : {
      "dnTemplate": "ou=locks,dc=openidm,dc=forgerock,dc=com",
      "objectClasses": [ "uidObject", "fr-idm-lock" ],
      "properties": {
        "_id": {
          "type": "simple", "ldapAttribute": "uid", "isRequired": true, "writability": "createOnly"
        },
        "nodeId": {
          "type": "simple", "ldapAttribute": "fr-idm-lock-nodeid"
        }
      }
    },
    "sync/queue" : {
      "dnTemplate": "ou=queue,ou=sync,dc=openidm,dc=forgerock,dc=com",
      "objectClasses": [ "uidObject", "fr-idm-syncqueue" ],
      "properties": {
        "_id": {
          "type": "simple", "ldapAttribute": "uid", "isRequired": true, "writability": "createOnly"
        },
        "syncAction": {
          "type": "simple", "ldapAttribute": "fr-idm-syncqueue-syncaction"
        },
        "resourceCollection": {
          "type": "simple", "ldapAttribute": "fr-idm-syncqueue-resourcecollection"
        },
        "resourceId": {
          "type": "simple", "ldapAttribute": "fr-idm-syncqueue-resourceid"
        },
        "mapping": {
          "type": "simple", "ldapAttribute": "fr-idm-syncqueue-mapping"
        },
        "objectRev": {
          "type": "simple", "ldapAttribute": "fr-idm-syncqueue-objectRev"
        },
        "oldObject": {
          "type": "json", "ldapAttribute": "fr-idm-syncqueue-oldobject"
        },
        "newObject": {
          "type": "json", "ldapAttribute": "fr-idm-syncqueue-newobject"
        },
        "context": {
          "type": "json", "ldapAttribute": "fr-idm-syncqueue-context"
        },
        "state": {
          "type": "simple", "ldapAttribute": "fr-idm-syncqueue-state"
        },
        "nodeId": {
          "type": "simple", "ldapAttribute": "fr-idm-syncqueue-nodeid"
        },
        "remainingRetries": {
          "type": "simple", "ldapAttribute": "fr-idm-syncqueue-remainingretries"
        },
        "createDate": {
          "type": "simple", "ldapAttribute": "fr-idm-syncqueue-createdate"
        }
      }
    }
  3. Update the sync mappings you wish to enable queued synchronization on to include the new queuedSync property:

    "queuedSync" : {
        "enabled" : true,
        "pageSize" : 100,
        "pollingInterval" : 1000,
        "maxQueueSize" : 20000
    },

For more information about this feature, see "Queued Synchronization" in the Integrator's Guide.

5.2.2. Enabling Privileges

Privileges are a new feature of internal roles, which allow for delegating certain administrative privileges to users, without needing to assign a full administrator role. An example where this may be useful is for support personnel who may need the ability to manage users, but shouldn't be able to manage other aspects of IDM:

  1. Before proceeding further, ensure you have run the required database scripts referenced in "Database Changes".

  2. Update your repo.jdbc.json or repo.ds.json files to include temporal constraints and privileges for internal roles:

    "internal/role" : {
        "table" : "internalrole",
        "objectToColumn" : {
            "_id" : "objectid",
            "_rev" : "rev",
            "name" : "name",
            "description" : "description",
            "temporalConstraints" : { "column" : "temporalConstraints", "type" : "JSON_LIST" },
            "condition" : "conditional",
            "privileges" : { "column" : "privs", "type" : "JSON_LIST" }
        }
    },

    If you are using DS, update your repo.ds.json file to include temporal constraints and privileges for internal roles:

    "internal/role": {
      "dnTemplate": "ou=roles,ou=internal,dc=openidm,dc=forgerock,dc=com",
      "objectClasses": [ "fr-idm-internal-role" ],
      "properties": {
        "_id": {
          "type": "simple", "ldapAttribute": "cn", "isRequired": true, "writability": "createOnly"
        },
        "name": {
          "type": "simple", "ldapAttribute": "fr-idm-name"
        },
        "description": {
          "type": "simple", "ldapAttribute": "description"
        },
        "temporalConstraints": {
          "type": "json", "ldapAttribute": "fr-idm-temporal-constraints", "isMultiValued": true
        },
        "condition": {
          "type": "simple", "ldapAttribute": "fr-idm-condition"
        },
        "privileges" : {
          "type": "json", "ldapAttribute": "fr-idm-privilege", "isMultiValued": true
        }
      }
    },
  3. Update policy.json to add privileges-related policies (policy.js in /bin/defaults/script/ has been updated with these new policies):

    {
        "resource" : "internal/role/*",
        "properties" : [
            {
                "name" : "name",
                "policies" : [
                    {
                        "policyId" : "required"
                    },
                    {
                        "policyId" : "not-empty"
                    },
                    {
                        "policyId" : "cannot-contain-characters",
                        "params" : {
                            "forbiddenChars" : [
                                "/*"
                            ]
                        }
                    }
                ]
            },
            {
                "name" : "privileges",
                "policies" : [
                    {
                        "policyId" : "valid-type",
                        "params" : {
                            "types" : [
                                "array"
                            ]
                        }
                    },
                    {
                        "policyId" : "valid-array-items",
                        "params" : {
                            "properties" : [
                                {
                                    "name" : "name",
                                    "policies" : [
                                        {
                                            "policyId" : "required"
                                        },
                                        {
                                            "policyId" : "not-empty"
                                        },
                                        {
                                            "policyId" : "valid-type",
                                            "params" : {
                                                "types" : [
                                                    "string"
                                                ]
                                            }
                                        }
                                    ]
                                },
                                {
                                    "name" : "path",
                                    "policies" : [
                                        {
                                            "policyId" : "required"
                                        },
                                        {
                                            "policyId" : "not-empty"
                                        },
                                        {
                                            "policyId" : "cannot-contain-characters",
                                            "params" : {
                                                "forbiddenChars" : [
                                                    "/*"
                                                ]
                                            }
                                        },
                                        {
                                            "policyId" : "valid-privilege-path"
                                        }
                                    ]
                                },
                                {
                                    "name" : "accessFlags",
                                    "policies" : [
                                        {
                                            "policyId" : "required"
                                        },
                                        {
                                            "policyId" : "not-empty"
                                        },
                                        {
                                            "policyId" : "valid-type",
                                            "params" : {
                                                "types" : [
                                                    "array"
                                                ]
                                            }
                                        },
                                        {
                                            "policyId" : "valid-accessFlags-object"
                                        }
                                    ]
                                },
                                {
                                    "name" : "actions",
                                    "policies" : [
                                        {
                                            "policyId" : "required"
                                        },
                                        {
                                            "policyId" : "valid-type",
                                            "params" : {
                                                "types" : [
                                                    "array"
                                                ]
                                            }
                                        }
                                    ]
                                },
                                {
                                    "name" : "permissions",
                                    "policies" : [
                                        {
                                            "policyId" : "required"
                                        },
                                        {
                                            "policyId" : "not-empty"
                                        },
                                        {
                                            "policyId" : "valid-type",
                                            "params" : {
                                                "types" : [
                                                    "array"
                                                ]
                                            }
                                        },
                                        {
                                            "policyId" : "valid-permissions"
                                        }
                                    ]
                                },
                                {
                                    "name" : "filter",
                                    "policies" : [
                                        {
                                            "policyId" : "valid-type",
                                            "params" : {
                                                "types" : [
                                                    "string",
                                                    "null"
                                                ]
                                            }
                                        }
                                    ]
                                }
                            ]
                        }
                    }
                ]
            }
        ]
    }
  4. Warning

    Because this step involves deleting data (the Roles column), we strongly recommend making a backup of your repository prior to making this change.

    (Optional) You can drop the Roles column from the internaluser table by running alter_internaluser.sql or alter_internaluser.ldif in your database.

    Once this is run, you can remove roles from the internal/user resource in your repo.jdbc.json or repo.ds.json file.

    The INTERNAL_USER object in authentication.json should also be updated to use authzRoles instead of roles:

    {
        "name" : "INTERNAL_USER",
        "properties" : {
            "queryId" : "credential-internaluser-query",
            "queryOnResource" : "internal/user",
            "propertyMapping" : {
                "authenticationId" : "username",
                "userCredential" : "password",
                "userRoles" : "authzRoles"
            },
            "defaultUserRoles" : [ ]
        },
        "enabled" : true
    },
  5. To allow the new privilege endpoint to be called, the following patterns need to be added to access.js:

    {
        "pattern"    : "privilege",
        "roles"      : "*",
        "methods"    : "action",
        "actions"    : "listPrivileges"
    },
    {
        "pattern"    : "privilege/*",
        "roles"      : "*",
        "methods"    : "read",
        "actions"    : "*"
    },

    Note

    If you already have custom access rules, take a moment to assess these rules before trying to apply new privileges. Any custom access rules created in access.js will be applied before privileges are considered, which may prevent the new privileges from being correctly applied.

    Note

    The ownIDP() customAuthz script referenced is broad by default, to accommodate any social identity providers you may use. For a production deployment, this should be replaced with ownRelationship() customAuthz scripts, applied to each of the specific social identity providers you intend to use. For example, if you wish to enable Google and Facebook as social identity providers, the managed/* pattern calling ownIDP() should be changed to:

    {
        "pattern"   : "managed/google",
        "roles"     : "internal/role/openidm-authorized",
        "methods"   : "read",
        "actions"   : "*",
        "customAuthz" : "ownRelationship()"
    },
    {
        "pattern"   : "managed/facebook",
        "roles"     : "internal/role/openidm-authorized",
        "methods"   : "read",
        "actions"   : "*",
        "customAuthz" : "ownRelationship()"
    }

    For more information about social identity providers, see "Configuring Social Identity Providers" in the Integrator's Guide.

  6. Finally, add and enable enableDynamicRoles in the JWT_SESSION session module in authentication.json:

    "enableDynamicRoles" : true,

For more information about privileges, see "Privileges and Delegation" in the Integrator's Guide.

5.2.3. Enabling Dynamic Role Calculation

To enable dynamically recalculating role assignments without requiring the user to log out and back in, open authentication.json, and enable the enableDynamicRoles property in the JWT_SESSION session module:

"enableDynamicRoles" : true

This will also enable privileges on internal roles, but can be used as its own feature even if you do not plan to use privileges.

Note

If your IDM instance has a large number of role assignments, performance may be impacted by enabling this feature.

5.2.4. Adding Thread IDs to Log Messages

IDM can now include the thread ID for the thread generating a log message, which can help when debugging. To enable this feature, open logging.properties and adjust the ConsoleHandler and FileHandler formatters to use ThreadIdLogFormatter:

java.util.logging.ConsoleHandler.formatter = org.forgerock.openidm.logger.ThreadIdLogFormatter
java.util.logging.FileHandler.formatter = org.forgerock.openidm.logger.ThreadIdLogFormatter

5.2.5. Access to Notifications

To enable access to the new notifications service used for the end user UI, make the following changes:

  1. Run the database update script (either create_notifications.sql or create_notifications.ldif) provided in bin/update/scripts/database-type/.

  2. Update your repo.jdbc.json file, adding the internal/notification mapping to your genericMapping object:

    "internal/notification" : {
        "mainTable" : "notificationobjects",
        "propertiesTable" : "notificationobjectproperties",
        "searchableDefault" : false,
        "properties" : {
            "/createDate" : {
                "searchable" : true
            },
            "/notificationType" : {
                "searchable" : true
            }
        }
    }

    If you are using DS, update the genericMapping resource collection in your repo.ds.json file to include the new internal/notification mapping:

    "internal/notification" : {
      "dnTemplate": "ou=notification,ou=internal,dc=openidm,dc=forgerock,dc=com"
    }
  3. To allow users to see their own information regardless of privileges, add the following patterns to access.js:

    // Grant users access to their own user metadata
    {
        "pattern"   : "internal/usermeta/*",
        "roles"     : "internal/role/openidm-authorized",
        "methods"   : "read",
        "actions"   : "*",
        "customAuthz" : "ownRelationship()"
    },
    // Grant users access to their own notifications
    {
        "pattern"   : "internal/notification/*",
        "roles"     : "internal/role/openidm-authorized",
        "methods"   : "read,delete",
        "actions"   : "*",
        "customAuthz" : "ownRelationship()"
    },
    {
        "pattern"   : "managed/user/*",
        "roles"     : "internal/role/openidm-authorized",
        "methods"   : "read,query",
        "actions"   : "*",
        "customAuthz" : "ownRelationshipCollection(['idps','_meta','_notifications'])"
    },
    {
        "pattern"   : "notification",
        "roles"     : "internal/role/openidm-authorized",
        "methods"   : "action",
        "actions"   : "deleteNotificationsForTarget",
        "customAuthz" : "request.additionalParameters.target === (context.security.authorization.component + '/' + context.security.authorization.id)"
    },
    {
        "pattern"   : "managed/*",
        "roles"     : "internal/role/openidm-authorized",
        "methods"   : "read",
        "actions"   : "*",
        "customAuthz" : "ownIDP()"
    }
  4. Remove the access.js code blocks for endpoint/usernotifications and endpoint/usernotifications/*.

  5. Remove the exports.createNotification code block from onUpdateUser.js.

  6. Replace onDelete-user-cleanup.js with postDelete-notification-cleanup.js.

  7. Remove the following file: userNotifications.js.

For more information on the new notification service, see "Configuring Notifications" in the Integrator's Guide.

5.2.6. Enabling File Uploads

IDM now provides a generic file upload service, which enables you to upload and save files either to the filesystem or to the repository. To enable this feature, take the following steps:

  1. Run the database update script (either create_files.sql or create_files.ldif) provided in bin/update/scripts/database-type/.

  2. Update the explicitMapping resource collection in your repo.jdbc.json file to include the new file mapping:

    "file" : {
        "table" : "files",
        "objectToColumn" : {
            "_id" : "objectid",
            "_rev" : "rev",
            "content" : "content"
        }
    }

    If you are using DS, update the genericMapping resource collection in your repo.ds.json file to include the new file mapping:

    "file" : {
      "dnTemplate": "ou=file,dc=openidm,dc=forgerock,dc=com"
    }

For more information about the file upload service, see "Uploading Files to the Server" in the Integrator's Guide.

5.2.7. Enabling Oracle UCP

Oracle UCP is a connection pool designed to cache JDBC connections. For IDM 6.5.0, it is an alternative to HikariCP for Oracle DB, as described in "Setting Up an Oracle DB Repository" in the Installation Guide. If you want to use Oracle UCP for IDM 6.5.0 instead of HikariCP, take the following steps:

  1. Find any custom settings that you created in your current datasource.jdbc-default.json file.

  2. Find the datasource.jdbc-ucp-oracle.json file in the /path/to/openidm/db/oracle/conf directory, and modify that file as needed for compatibility.

  3. Replace the datasource.jdbc-default.json file with the newly customized datasource-jdbc-ucp-oracle.json file in your project's conf/ subdirectory.

Chapter 6. How to Report Problems and Provide Feedback

If you have questions regarding ForgeRock Identity Management software that are not answered by the documentation, you can ask questions on the forum at https://forgerock.org/forum/fr-projects/openidm/.

When requesting help with a problem, include the following information:

  • Description of the problem, including when the problem occurs and its impact on your operation

  • Description of the environment, including the following information:

    • Machine type

    • Operating system and version

    • Repository type and version

    • Java version

    • IDM release version

    • Any patches or other software that might be affecting the problem

  • Steps to reproduce the problem

  • Any relevant access and error logs, stack traces, or core dumps

Chapter 7. Documentation Updates

"Documentation Change Log" tracks important changes to the documentation:

Documentation Change Log
DateDescription
2018-12-13

Fixed the following documentation issues:


Appendix A. Release Levels and Interface Stability

This appendix includes ForgeRock definitions for product release levels and interface stability.

A.1. ForgeRock Product Release Levels

ForgeRock defines Major, Minor, Maintenance, and Patch product release levels. The release level is reflected in the version number. The release level tells you what sort of compatibility changes to expect.

Release Level Definitions
Release LabelVersion NumbersCharacteristics

Major

Version: x[.0.0] (trailing 0s are optional)

  • Bring major new features, minor features, and bug fixes

  • Can include changes even to Stable interfaces

  • Can remove previously Deprecated functionality, and in rare cases remove Evolving functionality that has not been explicitly Deprecated

  • Include changes present in previous Minor and Maintenance releases

Minor

Version: x.y[.0] (trailing 0s are optional)

  • Bring minor features, and bug fixes

  • Can include backwards-compatible changes to Stable interfaces in the same Major release, and incompatible changes to Evolving interfaces

  • Can remove previously Deprecated functionality

  • Include changes present in previous Minor and Maintenance releases

Maintenance, Patch

Version: x.y.z[.p]

The optional .p reflects a Patch version.

  • Bring bug fixes

  • Are intended to be fully compatible with previous versions from the same Minor release


A.2. ForgeRock Product Interface Stability

ForgeRock products support many protocols, APIs, GUIs, and command-line interfaces. Some of these interfaces are standard and very stable. Others offer new functionality that is continuing to evolve.

ForgeRock acknowledges that you invest in these interfaces, and therefore must know when and how ForgeRock expects them to change. For that reason, ForgeRock defines interface stability labels and uses these definitions in ForgeRock products.

Interface Stability Definitions
Stability LabelDefinition

Stable

This documented interface is expected to undergo backwards-compatible changes only for major releases. Changes may be announced at least one minor release before they take effect.

Evolving

This documented interface is continuing to evolve and so is expected to change, potentially in backwards-incompatible ways even in a minor release. Changes are documented at the time of product release.

While new protocols and APIs are still in the process of standardization, they are Evolving. This applies for example to recent Internet-Draft implementations, and also to newly developed functionality.

Deprecated

This interface is deprecated and likely to be removed in a future release. For previously stable interfaces, the change was likely announced in a previous release. Deprecated interfaces will be removed from ForgeRock products.

Removed

This interface was deprecated in a previous release and has now been removed from the product.

Technology Preview

Technology previews provide access to new features that are evolving new technology that are not yet supported. Technology preview features may be functionally incomplete and the function as implemented is subject to change without notice. DO NOT DEPLOY A TECHNOLOGY PREVIEW INTO A PRODUCTION ENVIRONMENT.

Customers are encouraged to test drive the technology preview features in a non-production environment and are welcome to make comments and suggestions about the features in the associated forums.

ForgeRock does not guarantee that a technology preview feature will be present in future releases, the final complete version of the feature is liable to change between preview and the final version. Once a technology preview moves into the completed version, said feature will become part of the ForgeRock platform. Technology previews are provided on an “AS-IS” basis for evaluation purposes only and ForgeRock accepts no liability or obligations for the use thereof.

Internal/Undocumented

Internal and undocumented interfaces can change without notice. If you depend on one of these interfaces, contact ForgeRock support or email info@forgerock.com to discuss your needs.


Appendix B. Getting Support

For more information and resources about IDM and ForgeRock support, see the following sections:

B.1. Accessing Documentation Online

ForgeRock publishes comprehensive documentation online:

  • The ForgeRock Knowledge Base offers a large and increasing number of up-to-date, practical articles that help you deploy and manage ForgeRock software.

    While many articles are visible to community members, ForgeRock customers have access to much more, including advanced information for customers using ForgeRock software in a mission-critical capacity.

  • ForgeRock product documentation, such as this document, aims to be technically accurate and complete with respect to the software documented. It is visible to everyone and covers all product features and examples of how to use them.

B.2. Using the ForgeRock.org Site

The ForgeRock.org site has links to source code for ForgeRock open source software, as well as links to the ForgeRock forums and technical blogs.

If you are a ForgeRock customer, raise a support ticket instead of using the forums. ForgeRock support professionals will get in touch to help you.

B.3. Getting Support and Contacting ForgeRock

ForgeRock provides support services, professional services, training through ForgeRock University, and partner services to assist you in setting up and maintaining your deployments. For a general overview of these services, see https://www.forgerock.com.

ForgeRock has staff members around the globe who support our international customers and partners. For details, visit https://www.forgerock.com, or send an email to ForgeRock at info@forgerock.com.

Read a different version of :