Migrate Your Configuration

This chapter covers the steps required to migrate your IDM configuration to IDM 7.

There is no automated way to migrate a customized configuration to IDM 7, so you need to migrate customized configuration files manually. Assuming you are upgrading from IDM 6.5, there are three ways to do this:

  • Use the new IDM 7 configuration files as a base, and copy any customizations you have made to the new files.

    This is the preferred option, particularly if you have used version control on your configuration and can determine the exact changes you have applied.

  • Use your existing configuration files as a base, and add any new IDM 7 configuration to your existing files.

  • Use your existing configuration "as is" with no IDM 7 changes.

In most cases, a customized IDM 6.5 configuration will work without further modification on IDM 7.

Migrate Configuration Files

For customized files in your project's conf/ directory, check that the customizations are compatible with the changes outlined in Incompatible Changes. If there are no incompatible changes, either copy your old configuration files to your IDM 7 installation, or copy any customization into the corresponding new configuration files.

Migrate boot.properties

On the IDM 7 installation, edit the resolver/boot.properties file to match any customizations that you made on your IDM 6.5 server. Specifically, check the following elements:

  • The HTTP, HTTPS, and mutual authentication ports.

    If you changed the default ports in your IDM 6.5 deployment, make those same changes in the new boot.properties file.

  • Check that the keystore and truststore passwords match the current passwords for the keystore and truststore of your existing IDM deployment.

  • Check that the Changes to boot.properties are compatible with your customizations.

Migrate logging.properties

Check that the Changes to logging.properties are compatible with your customizations before you migrate your conf/logging.properties file.

Migrate Security Settings

Copy the contents of your IDM 6.5 security/ folder to the IDM 7 installation. By default, the IDM 6.5 security/ folder contains the following files:

  • keystore.jceks

  • truststore

The default IDM 7 security/ folder includes two new files (keystorepass and storepass), which contain the passwords to the keystore and truststore. Update these files with the passwords that you have set for your keystore and truststore.

Warning

If you do not copy your old truststore and keystore files to your new instance, you will be unable to decrypt anything that was encrypted by your old instance of IDM.

Migrate Custom Aliases

Creating custom aliases for default keys is no longer supported. If your old deployment used custom aliases for the default secret keys, migrate them using one of the following methods:

  • Generate new keys with the same custom aliases:

    1. After you have upgraded IDM, but before restarting the server, turn off the auto-generation of the default keys by setting "populateDefaults": false in your conf/secrets.json file.

    2. Generate new keys, using the same aliases you used in your previous deployment.

    3. Make sure that your conf/secrets.json file shows the custom aliases.

  • Use your old keys in the new IDM deployment:

    1. After you have upgraded IDM, but before restarting the server, turn off the auto-generation of the default keys by setting "populateDefaults": false in your conf/secrets.json file.

    2. Export the custom keys from the old keystore to the new keystore.

    3. Make sure that your conf/secrets.json file shows the custom aliases.

Migrate Custom Scripts

Migrate any custom scripts or default scripts that you have modified to the script directory of your IDM 7 instance. In general, custom and customized scripts should be located in the openidm/script directory of your existing IDM deployment.

For custom scripts, review Incompatible Changes. If you are confident that the scripts will work as intended on IDM 7, copy these scripts to the new instance.

If you modified a default IDM script, compare the default versions of the IDM 6.5 and IDM 7 scripts. If nothing has changed between the default versions, review your customizations against Incompatible Changes. If you are confident that your changes will work as intended on the new version, copy the customized scripts to the new script directory.

If a default script has changed since the IDM 6.5 release, test that your customizations work with the new default script before porting your changes to that new script.

Note

The bin/defaults/script/auth/amSessionCheck.js script has been removed in IDM 7. The only supported method of authentication through AM is by using AM bearer tokens and the rsFilter authentication module. For information on configuring an integrated deployment, see the Platform Setup Guide.

If you modify any shell scripts, such as startup.sh, you must migrate your changes manually to the new version of the script.

Migrate Provisioner Files

Change any customized provisioner configurations in your existing deployment to point to the connectors that are provided with IDM 7. Specifically, make sure that the connectorRef properties reflect the new connector versions, where applicable. For example: 

"connectorRef" : {
    "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
    "bundleVersion": "[1.4.0.0,1.6.0.0)",
    "connectorName": "org.identityconnectors.ldap.LdapConnector"
},

Alternatively, copy the connector .jar files from your existing deployment into the openidm/connectors directory of the new installation.

Migrate UI Customizations

If you have customized the Admin UI, review any custom UI files from your IDM 6.5 deployment (generally in the openidm/ui/admin/extension directory), and compare them against the corresponding IDM 7 files.

For each customized file, copy the corresponding default IDM 7 UI files to a openidm/ui/admin/extension directory on the new instance.

Apply your customizations to files in the new openidm/ui/admin/extension directory.

Read a different version of :