How do I upgrade the Java Remote Connector Server (RCS) for Identity Cloud and IDM?

Overview

This article provides information on upgrading the Java RCS and any connectors running on. There are two processes depending on whether you need to upgrade the RCS and connectors, or just update a connector running on the RCS:

• Upgrading the RCS and connectors
• Updating a connector on the RCS

Upgrading the RCS and connectors

You can upgrade the RCS and any connectors running on the RCS as follows:

1. Download the new RCS package and any required connectors from Backstage.
2. Stop the RCS by pressing CTRL + C, or q in the terminal where you started the server.
3. Rename the existing RCS directory to create a backup, for example:$ mv /path/to/openicf /path/to/openicf_old
4. Unpack the RCS package you downloaded (you should unpack this to the original directory to keep paths etc the same), for example:$ unzip openicf-zip-1.5.20.9.zip
5. Update the bundleVersion for the connector(s) you are upgrading if needed. You can do this as follows for each connector you are upgrading depending on whether you are using Identity Cloud or IDM:
   • Identity Cloud
     1. Retrieve the connector configuration by making a GET request as follows, replacing <tenant-env-fqdn> with your Identity Cloud tenant name, <connector-name> with the name of the connector and <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API (Authenticate to Identity Cloud REST API with Access Token):$ curl \ --request GET 'https://<tenant-env-fqdn>/openidm/config/provisioner.openicf/<connector-name>' \ --header 'authorization: Bearer <access-token>' \ --header 'content-type: application/json'
     2. Check the bundleVersion in the response includes the new connector version; some connectors define a range, whereas some define a specific version.
     3. Update the bundleVersion if required to include the new connector by making a PUT request with the connector configuration returned previously and the updated bundleVersion; it is best to specify a range to make future upgrades easier. Ensure you replace <tenant-env-fqdn>, <connector-name> and <access-token> as before. For example:$ curl \ --request PUT 'https://<tenant-env-fqdn>/openidm/config/provisioner.openicf/<connector-name>' \ --header 'authorization: Bearer <access-token>' \ --header 'content-type: application/json' --data-raw '{ ...    "connectorRef": {         "bundleName": "org.forgerock.openicf.connectors.ldap-connector",         "bundleVersion": "[1.5.19.0,1.6.0.0)",         "connectorHostRef": "demorcs",         "connectorName": "org.identityconnectors.ldap.LdapConnector"     }, ... }
   • IDM
     1. Open your provisioner configuration file (for example, provisioner.openicf-ldap.json), which is located in the /path/to/idm/conf directory.
     2. Check the bundleVersion includes the new connector version; some connectors define a range, whereas some define a specific version. 
     3. Update the bundleVersion if required to include the new connector. It is best to specify a range to make future upgrades easier, for example:"bundleVersion": "[1.5.19.0,1.6.0.0)",
6. Copy the connector .jar file(s) you downloaded to the /path/to/openicf/connectors directory.
7. Copy any custom connectors such as scripted connectors from your backup to the /path/to/openicf/connectors directory to retain your customizations.
8. Copy the following files from your backup to the new RCS directory to retain all your previous settings:
   • conf/ConnectorServer.properties
   • lib/framework/logback.xml (if you have set up the RCS for debug logging)
   • Any truststores and/or keystores. These are typically located in the /path/to/openicf/security directory.

For example:$ cd /path/to/openicf $ cp /path/to/openicf_old/conf/ConnectorServer.properties conf/ $ cp /path/to/openicf_old/lib/framework/logback.xml lib/framework/

9. Restart the RCS:$ /path/to/openicf/bin/ConnectorServer.sh /start
10. In Identity Cloud, you will need to:
    1. Make these changes to the RCS in all three Identity Cloud environments (Development, Staging and Production).
    2. Get your connector configuration changes promoted to Staging and Production.
    3. Restart your Staging and Production environments using the Restart API endpoint, for example:$ curl \ --request POST 'https://<tenant-env-fqdn>/environment/startup?_action=restart' \ --header 'authorization: Bearer <access-token>' \ --header 'Accept-API-Version: resource=1.0' \ --header 'Content-Type: application/json'

Updating a connector on the RCS

If you just need to update a connector running on the RCS, without upgrading the RCS, you can do this as follows:

1. Download the new connector version from Backstage.
2. Stop the RCS by pressing CTRL + C, or q in the terminal where you started the server.
3. Update the bundleVersion for the connector you are upgrading if needed. You can do this as follows depending on whether you are using Identity Cloud or IDM:
   • Identity Cloud
     1. Retrieve the connector configuration by making a GET request as follows, replacing <tenant-env-fqdn> with your Identity Cloud tenant name, <connector-name> with the name of the connector and <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API:$ curl \ --request GET 'https://<tenant-env-fqdn>/openidm/config/provisioner.openicf/<connector-name>' \ --header 'authorization: Bearer <access-token>' \ --header 'content-type: application/json'
     2. Check the bundleVersion in the response includes the new connector version; some connectors define a range, whereas some define a specific version.
     3. Update the bundleVersion if required to include the new connector by making a PUT request with the connector configuration returned previously and the updated bundleVersion; it is best to specify a range to make future upgrades easier. Ensure you replace <tenant-env-fqdn>, <connector-name> and <access-token> as before. For example:$ curl \ --request PUT 'https://<tenant-env-fqdn>/openidm/config/provisioner.openicf/<connector-name>' \ --header 'authorization: Bearer <access-token>' \ --header 'content-type: application/json' --data-raw '{ ...    "connectorRef": {         "bundleName": "org.forgerock.openicf.connectors.ldap-connector",         "bundleVersion": "[1.5.19.0,1.6.0.0)",         "connectorHostRef": "rcsName",         "connectorName": "org.identityconnectors.ldap.LdapConnector"     }, ... }
   • IDM
     1. Open your provisioner configuration file (for example, provisioner.openicf-ldap.json), which is located in the /path/to/idm/conf directory.
     2. Check the bundleVersion includes the new connector version; some connectors define a range, whereas some define a specific version. 
     3. Update the bundleVersion if required to include the new connector. It is best to specify a range to make future upgrades easier, for example:"bundleVersion": "[1.5.19.0,1.6.0.0)",
4. Copy the connector .jar file you downloaded to the /path/to/openicf/connectors directory and remove the old .jar file version.
5. Restart the RCS:$ /path/to/openicf/bin/ConnectorServer.sh /start
6. In Identity Cloud, you will need to:
   1. Make these changes to the RCS in all three Identity Cloud environments (Development, Staging and Production).
   2. Get your connector configuration changes promoted to Staging and Production.
   3. Restart your Staging and Production environments using the Restart API endpoint, for example:$ curl \ --request POST 'https://<tenant-env-fqdn>/environment/startup?_action=restart' \ --header 'authorization: Bearer <access-token>' \ --header 'Accept-API-Version: resource=1.0' \ --header 'Content-Type: application/json'

See Also

Using Checksums

How do I implement a Java Remote Connector Server (RCS) for Identity Cloud?

Remote connector configuration

Remote Connector Server (RCS) connectors