ICF 1.5.20.22

Upgrade Java RCS

Before you upgrade the Java RCS and any connectors running on it, you must update the connector configuration (specifically the bundleVersion) to include the versions you’re upgrading to. The bundleVersion defines a range of versions or a specific version.

If the bundleVersion doesn’t include the RCS version or connector version you’re upgrading to, the new RCS or connector won’t be usable after the upgrade.

Use a range for the bundleVersion to make future RCS and connector upgrades easier. The following example includes all versions starting from 1.5.0.0 up to, but not including, 1.6.0.0:

"bundleVersion": "[1.5.0.0,1.6.0.0)"

Update connector configuration

For IDM, you can update the connector over REST or in the provisioner file. For Identity Cloud, you can only update the configuration over REST.

Update connector configuration over REST

  1. Get the connector configuration:

    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Content-Type: application/json" \
--request GET \
"http://localhost:8080/openidm/config/provisioner.openicf/connectorName"
    Keep a copy of this configuration before making changes in case you need to re-create the connector.

  2. Check the bundleVersion in the response includes the new RCS and connector versions.

    If the bundleVersion in the response includes the new RCS and connector versions, move ahead to Upgrade the RCS and connectors; otherwise, continue to the next step of this procedure.

  3. Update the bundleVersion to include the new RCS and connector versions. This example uses non-matching brackets to specify a range:

    "bundleVersion": "[1.5.0.0,1.6.0.0)"
    For more information about version range options, refer to Connector reference properties.

  4. Use a PUT request to update the connector configuration previously returned with the updated bundleVersion:

    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data-raw '{complete-configuration}' \
"http://localhost:8080/openidm/config/provisioner.openicf/connectorName"

  5. If you are using Identity Cloud, promote your connector configuration changes to staging and production.

Update connector configuration in provisioner file (IDM only)

  1. Open the project-dir/conf/provisioner.openicf-connectorName file.

    If the bundleVersion in the file includes the new RCS and connector versions, move ahead to Upgrade the RCS and connectors; otherwise, continue to the next step of this procedure.

  2. Update the bundleVersion to include the new RCS and connector versions. This example uses non-matching brackets to specify a range:

    "bundleVersion": "[1.5.0.0,1.6.0.0)"
    For more information about version range options, refer to Connector reference properties.

Upgrade the RCS and connectors

Upgrade the RCS and any connectors running on the RCS

You can upgrade a connector running on the RCS without upgrading the RCS if needed.

  1. Download the new Java RCS and any required connectors from ForgeRock BackStage download site.

  2. Stop the RCS:

    • If the RCS is running in a terminal, press CTRL+C or q.

    • If the RCS is running as a service, stop the service:

      sudo systemctl stop rcs.service

  3. Rename the existing RCS directory to create a backup:

    mv /path/to/openicf /path/to/openicf_old

  4. Extract the downloaded Java RCS to the original directory (/path/to/openicf).

  5. Copy the downloaded connector .jar file(s) to the /path/to/openicf/connectors directory.

  6. Copy any custom connectors, such as scripted connectors from your backup to the /path/to/openicf/connectors directory to retain your customizations.

  7. Copy the following files from your backup to the new RCS directory to retain your previous settings:

    • conf/ConnectorServer.properties

    • conf/logback.xml (if the RCS is set up for debug logging)

    • Any truststores and keystores. These are typically located in the /path/to/openicf/security directory.

  8. Start the RCS:

    • Terminal

    • Service

    /path/to/openicf/bin/ConnectorServer.sh /run
    sudo systemctl start rcs.service

In Identity Cloud, you must:

  1. Make these changes to the RCS in all three Identity Cloud environments (development, staging, and production).

  2. Restart your staging and production environments using the Restart API endpoint:

    curl \
--header "authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json"
--request POST \
"https://<tenant-env-fqdn>/environment/startup?_action=restart"

Upgrade a connector running on the RCS

You can upgrade a connector running on the RCS without upgrading the RCS itself.

  1. Download the new connector version from ForgeRock BackStage download site.

  2. Stop the RCS:

    • If the RCS is running in a terminal, press CTRL+C or q.

    • If the RCS is running as a service, stop the service:

      sudo systemctl stop rcs.service

  3. Copy the downloaded connector .jar file to the /path/to/openicf/connectors directory and remove the old .jar file version.

  4. Start the RCS:

    • Terminal

    • Service

    /path/to/openicf/bin/ConnectorServer.sh /run
    sudo systemctl start rcs.service

In Identity Cloud, you must:

  1. Make these changes to the RCS in all three Identity Cloud environments (development, staging, and production).

  2. Restart your staging and production environments using the Restart API endpoint:

    curl \
--header "authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json"
--request POST \
"https://<tenant-env-fqdn>/environment/startup?_action=restart"
Copyright © 2010-2024 ForgeRock, all rights reserved.