RCS in Identity Cloud

This book provides information on using the Remote Connector Server (RCS) in the Identity Cloud, including implementing and upgrading the RCS.


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

The purpose of this article is to provide information on implementing an RCS for Identity Cloud and includes troubleshooting steps.

Introduction

The Java® RCS is required for Identity Cloud to remotely connect to any supported identity resource server via connectors. These connectors run in Identity Cloud. See About Identity Cloud connectors for further information. 

You can run the connector server on the same host as the identity resource server, or you can run it on a different host, for example, that’s dedicated to hosting only connectors.

Preparing to implement the RCS

Before you start implementing the RCS, you should consider the following recommendations:

  • Setting up the RCS, connectors and mappings should be the first thing you do during implementation to ensure you have user data flowing into Identity Cloud.
  • You should implement the RCS in all three Identity Cloud environments (Development, Staging and Production).
  • Always use dedicated RCS instances and external identity servers for each Identity Cloud environment because each environment has different needs. For example, Development will only contain test data whereas Production will hold real data. Separating the RCS and external identity servers for each environment means you will not impact Production data during testing.
  • Physically locate the RCS as close to the external identity servers as possible to reduce latency.
  • Cluster the RCS to achieve high availability. Although this step is considered optional, it is strongly recommended to prevent the RCS from being a single point of failure.

Prerequisites

  • You have three working Identity Cloud environments (Development, Staging, and Production).
  • You have corresponding external identity servers set up for each environment.
  • Java 11 is installed on the server where you want to install the RCS.
  • You have set the JAVA_HOME environment variable to point to your Java 11 install.

Implementing the RCS

Note

The documentation covers the steps needed to implement the RCS: Before you begin. This article references the steps in the documentation, but goes further to include additional checks along the way to help ensure a successful implementation. It also reinforces the need to implement the RCS in all three environments (Development, Staging, and Production).

The steps to implement the RCS are as follows:

  1. Navigate to the Admin UI in your Identity Cloud Development environment.
  2. Register a remote server.
  3. Reset the client secret (unless you have already done this and know the password).
  4. Download a remote server.
  5. Configure a remote server to connect to Identity Cloud.
    • In the Development environment, you should only specify one instance in the connectorserver.url, for example: wss://<tenant-name>.forgeblocks.com/openicf/0
    • In the Staging and Production environments, you should specify three instances for the connectorserver.url, for example: wss://<tenant-name>.forgeblocks.com/openicf/0 wss://<tenant-name>.forgeblocks.com/openicf/1 wss://<tenant-name>.forgeblocks.com/openicf/2
  6. Check that the remote server connection is working before you continue by navigating to Identities > Connect in the Admin UI. It should show as connected.
  7. Install and configure a connector:
    • In the Identity Cloud Admin UI, navigate to Native Consoles > Identity Management > Configure > Connectors to configure your connector.
    • If you want to use a scripted connector or configure a connector that is not supported in the Admin UI, you can configure it via REST: Create a connector configuration over REST.
  8. Check that the connector is successfully connected to the external identity server by navigating to the Data tab in the connector. You should see user data from your external identity server.
  9. Create a mapping between identities in Identity Cloud and identities in your identity server:
  10. Perform an initial reconciliation based on your mapping.
  11. Register a server cluster if you plan to set up load balancing or failover.
  12. Navigate to the Admin UI in your Identity Cloud Staging environment.
  13. Repeat steps 2 to 11 in your Staging environment.
  14. Navigate to the Admin UI in your Identity Cloud Production environment.
  15. Repeat steps 2 to 11 in your Production environment.

After implementation

Once you have successfully implemented the RCS, you should:

Changing the JVM heap size

Changing the JVM heap size can improve performance and reduce the time it takes to run reconciliations. You should try different heap sizes to see what impact it has to determine the best heap size for your setup.

You can set the JVM heap size via the OPENICF_OPTS environment variable. For example, to set the maximum heap size to 1GB, you would enter the following prior to starting the RCS:

On Unix® and Linux® systems:

$ cd /path/to/openicf/bin $ export OPENICF_OPTS="-Xmx1024m" $ ./ConnectorServer.sh /run

On Microsoft® Windows® systems:

C:\> cd \path\to\openicf\bin C:\path\to\openicf\bin> set OPENICF_OPTS=-Xmx1024m  C:\path\to\openicf\bin> ConnectorServer.bat /run

Troubleshooting

First you should establish whether the RCS is connected and if the connector is receiving data:

  • Check if the remote server connection is working by navigating to Identities > Connect in the Admin UI. It should show as connected.
  • Check that the connector is successfully connected to the external identity server by navigating to Native Consoles > Identity Management > Configure > [Connector] > Data. You should see user data from your external identity server if it's receiving data.
Note

If you are seeing unexplained slowness or instability in your Development environment, you should check connectorserver.url is set correctly in your ConnectorServer.properties file. Development environments should only list one URL, for example: wss://<tenant-name>.forgeblocks.com/openicf/0

If the RCS is not connected, you should:

  1. Verify the settings in your ConnectorServer.properties file (located in the /path/to/openicf/conf directory) are correct for your environment and update if needed.
  2. Reset the client secret to the known password if there is a chance someone else could have changed it.
  3. Enable debug logging as detailed in How do I enable debug logging and log rotation for the Remote Connector Server (RCS)?
  4. Check the logs (located in the /path/to/openicf/logs directory) for clues to see if you can resolve your issues yourself. Common error messages to look out for are:
Error message Details

 [name of rcs] 0 active WebSocket(s), 3 remaining permits

(repeating)

This error message means the RCS cannot obtain a connection to Identity Cloud. You should check the following settings in the ConnectorServer.properties file and update as needed:

  • connectorserver.url: should be similar to:
    • wss://<tenant-name>.forgeblocks.com/openicf/0 in your Development environment.
    • wss://<tenant-name>.forgeblocks.com/openicf/0 wss://<tenant-name>.forgeblocks.com/openicf/1 wss://<tenant-name>.forgeblocks.com/openicf/2 in your Staging and Production environments.
  • connectorserver.tokenEndpoint: should be similar to: https://<tenant-name>.forgeblocks.com/am/oauth2/realms/root/realms/alpha/access_token
  • connectorserver.clientSecret: should contain the correct client secret for the RCSClient in the alpha realm.
StaggeredConnectionCreator: timed out resolving connection promise

This error message means the HTTP connection is being made but upgrading the connection to a WebSocket is failing because the RCS points to an invalid URL. You should check the following setting in the ConnectorServer.properties file and update as needed:

  • connectorserver.url: should be similar to:
    • wss://<tenant-name>.forgeblocks.com/openicf/0 in your Development environment.
    • wss://<tenant-name>.forgeblocks.com/openicf/0 wss://<tenant-name>.forgeblocks.com/openicf/1 wss://<tenant-name>.forgeblocks.com/openicf/2 in your Staging and Production environments.

If the connector is not receiving data, you should verify the connector settings are correct and update them if needed.

If you're still experiencing issues after taking these troubleshooting steps, please raise a ticket with ForgeRock Support.

Raising a ticket

To help us troubleshoot issues with the RCS, please gather the following details and submit them with your support ticket:

  • Collect the logs from the RCS server (located in the /path/to/openicf/logs directory) and indicate what timezone is used for logging.
  • Collect all the idm- prefixed logs from Identity Cloud as explained in View Audit Logs.
  • Collect the ConnectorServer.properties file (located in the /path/to/openicf/conf directory).
  • Confirm the versions of the RCS and connectors you are experiencing issues with.
  • Provide details about the environment where you are running the RCS, including whether they are clustered?
  • Provide details of any configuration changes you made prior to experiencing issues.
  • Provide any scripts you use in your connectors.

See Also

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

How do I run a Remote Connector Server (RCS) as a Service?

RCS in Identity Cloud

Sync Identities

About Identity Cloud connectors


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

The purpose of this article is to provide instructions on how to upgrade the RCS for Identity Cloud and IDM.

Upgrading the RCS

You can upgrade the RCS as follows:

  1. Download the new RCS package 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.0.zip
  5. 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)

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/

  1. Restart the RCS:$ /path/to/openicf/bin/ConnectorServer.sh /run

See Also

Using Checksums

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

Remote Connectors


How do I set up a scripted SQL connector using the Remote Connector Server (RCS) with Identity Cloud?

The purpose of this article is to demonstrate how to set up a scripted SQL connector using the RCS with Identity Cloud.

Overview

This article provides instructions on how to set up a scripted SQL connector using the RCS with Identity Cloud. It is intended for demonstration purposes only, and uses a sample MySQL™ database in a Docker image and sample Groovy scripts. The scripts provided with this sample are specific to the sample. You must customize these scripts to address the requirements of your specific deployment. The sample scripts are a good starting point on which to base your customization.

Steps involved:

  1. Set up the RCS
  2. Create the Docker container with the sample MySQL database
  3. Copy the MySQL Connector to the RCS
  4. Create the scripted SQL connector in Identity Cloud
  5. Verify the connector in Identity Cloud
  6. Sync the MySQL database with Identity Cloud

Prerequisites

  • You have a working Identity Cloud tenant.
  • You have installed and configured a Docker engine. This must be on the same machine that you will install the RCS on.

Setting up the RCS

You'll need to install the Java® RCS which is required for Identity Cloud to connect remotely to any supported identity resource server via a connector. See About Identity Cloud Connectors for further information.

Install the RCS by following steps 1 through 3 in Sync Identities:

  1. Register a remote server
  2. Download a remote server
  3. Configure the remote server to connect to Identity Cloud

Once you've completed these steps, verify that the RCS server is connected: 

  • In the Identity Cloud Admin UI, navigate to Identities > Connect and check RCS server status is ‘Connected'.

Creating the Docker container with the sample MySQL database

Caution

Disclaimer for the following Docker image, please review before implementing this sample. This image is just a sample for demonstration purposes. Creating and using Docker images is outside the scope of ForgeRock support; if you want more tailored advice, consider engaging Deployment Support Services.  

Follow these steps to create a Docker container with an external MySQL database (named “hrdb”). This database is pre-populated with sample data and a user (called forgerock) that the connector will authenticate as.

  1. Create the Docker container with the external MySQL database: $ docker run --name mysql-for-rcs -p3306:3306 -e MYSQL_ROOT_PASSWORD=Pa$$w0rd -d sandeepc0/mysql-hrdb
  2. Verify that a MySQL instance is running in the Docker container: $ docker exec -it mysql-for-rcs mysql -u root -pPa$$w0rdThe mysql > prompt is displayed if the MySQL instance is running in the Docker container as expected.
  3. Verify that the database is initialized:
    1. Specify the database to use:  mysql> use hrdb; Database changed
    2. Return a list of users:mysql> select uid from users; +--------+ | uid | +--------+ | bob | | rowley | | louis | | john | | jdoe | +--------+ 5 rows in set (0.00 sec)If a list of users is returned, this indicates that the database has initialized successfully.
    3. Exit MySQL:mysql> exit

Copying the MySQL Connector to the RCS

  1. Download MySQL Connector/J version 5.1 or later.
  2. Unzip the downloaded file and copy the mysql-connector-java-x.x.x.jar to /path/to/openicf/lib/framework on the machine where you installed the RCS.
  3. Restart the RCS:$ /path/to/openicf/bin/ConnectorServer.sh /run

Creating the scripted SQL connector in Identity Cloud

  1. Download the latest IDM distribution from here and unzip it.
  2. Modify the contents of provisioner.openicf-hrdb.json (located in /path/to/idm/samples/scripted-sql-with-mysql/conf) as shown in the following example. You'll need to:
    1. Add connectorHostRef, systemType and displayName under connectorRef as shown, and change the connectorHostRef to the name of your RCS client.
    2. Change the username and password under configurationProperties to forgerock and Pa$$w0rd respectively.
    3. Change the scriptRoots path under configurationProperties to replace /path/to/openicf with the path to your RCS client.
    4. Remove the systemActions section completely.{    "connectorRef" : {         "connectorHostRef": "<RCSClientName>",         "systemType": "provisioner.openicf",         "displayName": "Scripted SQL Connector",         "bundleName" : "org.forgerock.openicf.connectors.scriptedsql-connector",         "bundleVersion" : "[1.5.0.0,1.6.0.0)",         "connectorName" : "org.forgerock.openicf.connectors.scriptedsql.ScriptedSQLConnector"     },     "producerBufferSize" : 100,     "connectorPoolingSupported" : true,     "poolConfigOption" : {         "maxObjects" : 10,         "maxIdle" : 10,         "maxWait" : 150000,         "minEvictableIdleTimeMillis" : 120000,         "minIdle" : 1     },     "operationTimeout" : {         "CREATE" : -1,         "TEST" : -1,         "AUTHENTICATE" : -1,         "SEARCH" : -1,         "VALIDATE" : -1,         "GET" : -1,         "UPDATE" : -1,         "DELETE" : -1,         "SCRIPT_ON_CONNECTOR" : -1,         "SCRIPT_ON_RESOURCE" : -1,         "SYNC" : -1,         "SCHEMA" : -1     },     "configurationProperties" : {         "username" : "forgerock",         "password" : "Pa$$w0rd",         "driverClassName" : "com.mysql.jdbc.Driver",         "url" : "jdbc:mysql://localhost:3306/hrdb?serverTimezone=UTC",         "autoCommit" : true,         "validationQuery" : "SELECT 1 FROM DUAL",         "validationInterval" : "2000",         "testOnBorrow" : true,         "authenticateScriptFileName" : "AuthenticateScript.groovy",         "createScriptFileName" : "CreateScript.groovy",         "testScriptFileName" : "TestScript.groovy",         "searchScriptFileName" : "SearchScript.groovy",         "deleteScriptFileName" : "DeleteScript.groovy",         "updateScriptFileName" : "UpdateScript.groovy",         "syncScriptFileName" : "SyncScript.groovy",         "schemaScriptFileName" : "SchemaScript.groovy",         "scriptRoots" : [             "/path/to/openicf/connector_scripts/scripted_sql/"         ]     },     "resultsHandlerConfig": {         "enableAttributesToGetSearchResultsHandler": true     },     "syncFailureHandler" : {         "maxRetries" : 5,         "postRetryAction" : "logged-ignore"     },     "objectTypes" : {         "group" : {             "$schema" : "http://json-schema.org/draft-03/schema",             "id" : "__GROUP__",             "type" : "object",             "nativeType" : "__GROUP__",             "properties" : {                 "name" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "__NAME__",                     "nativeType" : "string"                 },                 "gid" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "gid",                     "nativeType" : "string"                 },                 "description" : {                     "type" : "string",                     "required" : false,                     "nativeName" : "description",                     "nativeType" : "string"                 },                 "users" : {                     "type" : "array",                     "nativeName" : "users",                     "nativeType" : "object",                     "items" : {                         "type" : "object",                         "properties" : {                             "uid" : {                                 "type" : "string"                             }                         }                     }                 }             }         },         "organization" : {             "$schema" : "http://json-schema.org/draft-03/schema",             "id" : "organization",             "type" : "object",             "nativeType" : "organization",             "properties" : {                 "name" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "__NAME__",                     "nativeType" : "string"                 },                 "description" : {                     "type" : "string",                     "required" : false,                     "nativeName" : "description",                     "nativeType" : "string"                 }             }         },         "account" : {             "$schema" : "http://json-schema.org/draft-03/schema",             "id" : "__ACCOUNT__",             "type" : "object",             "nativeType" : "__ACCOUNT__",             "properties" : {                 "firstName" : {                     "type" : "string",                     "nativeName" : "firstname",                     "nativeType" : "string",                     "required" : true                 },                 "email" : {                     "type" : "string",                     "nativeName" : "email",                     "nativeType" : "string"                 },                 "cars" : {                     "type" : "array",                     "nativeName" : "cars",                     "nativeType" : "object",                     "items" : {                         "type" : "object",                         "properties" : {                             "year" : {                                 "type" : "string"                             },                             "make" : {                                 "type" : "string"                             },                             "model" : {                                 "type" : "string"                             }                         }                     }                 },                 "password" : {                     "type" : "string",                     "nativeName" : "password",                     "nativeType" : "string",                     "flags" : [ "NOT_READABLE", "NOT_RETURNED_BY_DEFAULT" ]                 },                 "uid" : {                     "type" : "string",                     "nativeName" : "__NAME__",                     "required" : true,                     "nativeType" : "string"                 },                 "fullName" : {                     "type" : "string",                     "nativeName" : "fullname",                     "nativeType" : "string"                 },                 "lastName" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "lastname",                     "nativeType" : "string"                 },                 "organization" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "organization",                     "nativeType" : "string"                 },                 "timestamp" : {                     "type" : "string",                     "nativeName" : "timestamp",                     "nativeType" : "string",                     "flags" : [                         "NOT_CREATEABLE",                         "NOT_UPDATEABLE"                     ]                 }             }         }     },     "operationOptions" : {     } }
  3. Create a connector_scripts/scripted_sql directory in /path/to/openicf on the machine where you installed the RCS:$ cd path/to/openicf $ mkdir -p connector_scripts/scripted_sql
  4. Copy all the Groovy scripts from /path/to/idm/samples/scripted-sql-with-mysql/tools to /path/to/openicf/connector_scripts/scripted_sql.
  5. Create the connector configuration in Identity Cloud by making a PUT request with the JSON content in provisioner.openicf-hrdb.json (modified in Step 2), replacing <tenant-name> with your Identity Cloud tenant name:$ curl 'https://<tenant-name>.forgeblocks.com/openidm/config/provisioner.openicf/hrdb' \  -X 'PUT' \   -H 'authorization: Bearer <bearer token>' \   -H 'content-type: application/json' \   --data-raw '{     "connectorRef" : {         "connectorHostRef": "<RCSClientName>",         "systemType": "provisioner.openicf",         "displayName": "Scripted SQL Connector",         "bundleName" : "org.forgerock.openicf.connectors.scriptedsql-connector",         "bundleVersion" : "[1.5.0.0,1.6.0.0)",         "connectorName" : "org.forgerock.openicf.connectors.scriptedsql.ScriptedSQLConnector"     },     "producerBufferSize" : 100,     "connectorPoolingSupported" : true,     "poolConfigOption" : {         "maxObjects" : 10,         "maxIdle" : 10,         "maxWait" : 150000,         "minEvictableIdleTimeMillis" : 120000,         "minIdle" : 1     },     "operationTimeout" : {         "CREATE" : -1,         "TEST" : -1,         "AUTHENTICATE" : -1,         "SEARCH" : -1,         "VALIDATE" : -1,         "GET" : -1,         "UPDATE" : -1,         "DELETE" : -1,         "SCRIPT_ON_CONNECTOR" : -1,         "SCRIPT_ON_RESOURCE" : -1,         "SYNC" : -1,         "SCHEMA" : -1     },     "configurationProperties" : {         "username" : "forgerock",         "password" : "Pa$$w0rd",         "driverClassName" : "com.mysql.jdbc.Driver",         "url" : "jdbc:mysql://localhost:3306/hrdb?serverTimezone=UTC",         "autoCommit" : true,         "validationQuery" : "SELECT 1 FROM DUAL",         "validationInterval" : "2000",         "testOnBorrow" : true,         "authenticateScriptFileName" : "AuthenticateScript.groovy",         "createScriptFileName" : "CreateScript.groovy",         "testScriptFileName" : "TestScript.groovy",         "searchScriptFileName" : "SearchScript.groovy",         "deleteScriptFileName" : "DeleteScript.groovy",         "updateScriptFileName" : "UpdateScript.groovy",         "syncScriptFileName" : "SyncScript.groovy",         "schemaScriptFileName" : "SchemaScript.groovy",         "scriptRoots" : [             "/path/to/openicf/connector_scripts/scripted_sql/"         ]     },     "resultsHandlerConfig": {         "enableAttributesToGetSearchResultsHandler": true     },     "syncFailureHandler" : {         "maxRetries" : 5,         "postRetryAction" : "logged-ignore"     },     "objectTypes" : {         "group" : {             "$schema" : "http://json-schema.org/draft-03/schema",             "id" : "__GROUP__",             "type" : "object",             "nativeType" : "__GROUP__",             "properties" : {                 "name" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "__NAME__",                     "nativeType" : "string"                 },                 "gid" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "gid",                     "nativeType" : "string"                 },                 "description" : {                     "type" : "string",                     "required" : false,                     "nativeName" : "description",                     "nativeType" : "string"                 },                 "users" : {                     "type" : "array",                     "nativeName" : "users",                     "nativeType" : "object",                     "items" : {                         "type" : "object",                         "properties" : {                             "uid" : {                                 "type" : "string"                             }                         }                     }                 }             }         },         "organization" : {             "$schema" : "http://json-schema.org/draft-03/schema",             "id" : "organization",             "type" : "object",             "nativeType" : "organization",             "properties" : {                 "name" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "__NAME__",                     "nativeType" : "string"                 },                 "description" : {                     "type" : "string",                     "required" : false,                     "nativeName" : "description",                     "nativeType" : "string"                 }             }         },         "account" : {             "$schema" : "http://json-schema.org/draft-03/schema",             "id" : "__ACCOUNT__",             "type" : "object",             "nativeType" : "__ACCOUNT__",             "properties" : {                 "firstName" : {                     "type" : "string",                     "nativeName" : "firstname",                     "nativeType" : "string",                     "required" : true                 },                 "email" : {                     "type" : "string",                     "nativeName" : "email",                     "nativeType" : "string"                 },                 "cars" : {                     "type" : "array",                     "nativeName" : "cars",                     "nativeType" : "object",                     "items" : {                         "type" : "object",                         "properties" : {                             "year" : {                                 "type" : "string"                             },                             "make" : {                                 "type" : "string"                             },                             "model" : {                                 "type" : "string"                             }                         }                     }                 },                 "password" : {                     "type" : "string",                     "nativeName" : "password",                     "nativeType" : "string",                     "flags" : [ "NOT_READABLE", "NOT_RETURNED_BY_DEFAULT" ]                 },                 "uid" : {                     "type" : "string",                     "nativeName" : "__NAME__",                     "required" : true,                     "nativeType" : "string"                 },                 "fullName" : {                     "type" : "string",                     "nativeName" : "fullname",                     "nativeType" : "string"                 },                 "lastName" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "lastname",                     "nativeType" : "string"                 },                 "organization" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "organization",                     "nativeType" : "string"                 },                 "timestamp" : {                     "type" : "string",                     "nativeName" : "timestamp",                     "nativeType" : "string",                     "flags" : [                         "NOT_CREATEABLE",                         "NOT_UPDATEABLE"                     ]                 }             }         }     },     "operationOptions" : {     } }

Verifying the connector in Identity Cloud

Follow these steps to verify that the connector is working and can return data from the database.

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Identity Management > Configure > Connectors.

The Hrdb connector is displayed and shown as “Active”. 

 
  1. Select the Hrdb connector and navigate to Data tab > Account.

Account data from the hrdb database is displayed:

 

Synchronizing the MySQL database with Identity Cloud

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Identity Management > Create Mapping.
  2. Select the source (Hrdb) and target resource (for example, Managed Alpha_user) and click Create mapping > Create.
  3. Click Properties > Attributes Grid > Add Missing Required Properties.
  4. Click the Edit icon next to each target property to configure the following corresponding source properties:
    • givenName - firstName
    • mail - email
    • sn - lastName
    • userName - uid
 
  1. Click the Behaviors tab and select Default Actions from the Current Policy drop-down and click Save.
  2. Click Reconcile to sync the identities.

Once the reconciliation is complete, check that the identities in the hrdb database have been sync'd to Identity Cloud: 

  • In the Identity Cloud Admin UI, navigate to Identities > Manage > Alpha/Bravo Realm Users and search for the identities.

See Also

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

Create a connector configuration over REST

Connect to a MySQL Database With ScriptedSQL


How do I integrate Identity Cloud with Shopify using the Remote Connector Server (RCS) and a scripted REST Connector?

The purpose of this article is to provide information on integrating Identity Cloud with Shopify® to synchronize customer accounts.

Overview

This article provides information on integrating Identity Cloud with Shopify to synchronize customer accounts. To do this you will need to set up a Remote Connector Server (RCS) and configure a scripted REST Connector for Shopify.

Summary of the steps involved:

  1. Set up the Remote Connector Server (RCS)
  2. Configure a Scripted REST Connector
  3. Create a Shopify app
  4. Link the scripted REST Connector to the Shopify customer API
  5. Configure mappings to sync between Identity Cloud and Shopify

Prerequisites

Setting up the Remote Connector Server (RCS)

You'll need to install the Java® Remote Connector Server (RCS) which is required for Identity Cloud to connect remotely to any supported identity resource server via a connector. See About Identity Cloud Connectors for further information.

Install and configure the RCS

Install the RCS by following steps 1 through 3 in Sync Identities:

  1. Register a remote server
  2. Download and configure the remote server
  3. Configure the remote server to connect to Identity Cloud

Once you've completed these steps, verify that the RCS server is connected: 

  • In the Identity Cloud Admin UI, navigate to Identities > Connect and check RCS server status is ‘Connected'.

Add the Shopify Groovy scripts to the RCS

Caution

The scripts provided here are sufficient for demo purposes and should not be used for production without additional development. For example, the SearchScript.groovy script supports only very limited search queries, and there is currently no support for pagination which would be required for large datasets.

The scripted REST Connector uses Groovy scripts to implement actions on a remote data source. 

  1. Download the tools.zip file: tools.zip (18 kB)
  2. Move the tools.zip file to the root directory of your RCS and extract the zip.

A tools folder is created containing the required Shopify Groovy script files.

Configuring a Scripted REST Connector

You'll configure the Scripted REST Connector using REST calls, as outlined in Create a connector configuration over REST

Before you begin 

  1. Get an access token for making REST calls.
  2. Set an environment variable with your access token value, for example: export TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkNWE4NDVjMy03MjFh LTQzN2QtYjIyZi04ZjNlNzUyNDExNWIiLCJjdHMiOiJPQVVUSDJfR1JBTlRfU0VUIiwiYXV0aF9sZXZ lbCI6MCwiYXVkaXRUcmFja2luZ0lkIjoiYjU4M2Q2NGUtM2VlYi00M2Y5LWI5ZTctZDM4MDI4MDQyYW JmLTY0MyIsImlzcyI6Imh0dHBzOi8vb3BlbmFtLWNhcmlhZ2EtMDUuZm9yZ2VibG9ja3MuY29tL2FtL"

Configure the Scripted REST Connector

  1. Run the following command to list the available connectors, replacing <tenant-name> with the name of your Identity Cloud tenant. curl \  -H 'authorization: Bearer '"$TOKEN" \   --header "Accept-API-Version: resource=1.0" \   --request POST \   'https://<tenant-name>.forgeblocks.com/openidm/system?_action=availableConnectors'

Your connector server returns a list of available connectors. This list includes details of the Scripted Rest Connector, similar to the example below, which you'll use in the next steps.{      "connectorHostRef": "rcs",       "displayName": "Scripted REST Connector",       "bundleVersion": "1.5.20.0",       "systemType": "provisioner.openicf",       "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector",       "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"     }

  1. Run the following command to generate the core configuration, replacing <tenant-name> with the name of your Identity Cloud tenant. In the connectorRef section, make sure you include your Scripted Rest Connector details generated in the previous step, for example:curl 'https://<tenant-name>.forgeblocks.com/openidm/system?_action=createCoreConfig' \  -H 'authorization: Bearer '"$TOKEN" \   -H 'content-type: application/json' \   -H 'accept: application/json, text/javascript, */*; q=0.01' \   --data-binary '{"connectorRef" :     {       "connectorHostRef": "rcs",       "displayName": "Scripted REST Connector",       "bundleVersion": "1.5.20.0",       "systemType": "provisioner.openicf",       "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector",       "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"     }   }'
  2. Run the following command to send the Shopify connector configuration to Identity Cloud, replacing <tenant-name> with the name of your Identity Cloud tenant. In the connectorRef section, make sure you include the correct Scripted Rest Connector details.

The configuration includes an example schema, which includes personal details, as well as marketing preferences, total spent, and notes on the customer record.curl -i --location --request PUT 'https://<tenant-name>.forgeblocks.com/openidm/config/provisioner.openicf/shopify3' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer '"$TOKEN" \ --data-raw '{  "connectorRef": {     "connectorHostRef": "rcs",     "displayName": "Scripted REST Connector",     "bundleVersion": "1.5.20.0",     "systemType": "provisioner.openicf",     "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector",     "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"   },   "poolConfigOption": {     "maxObjects": 10,     "maxIdle": 10,     "maxWait": 150000,     "minEvictableIdleTimeMillis": 120000,     "minIdle": 1   },   "resultsHandlerConfig": {     "enableNormalizingResultsHandler": false,     "enableFilteredResultsHandler": false,     "enableCaseInsensitiveFilter": false,     "enableAttributesToGetSearchResultsHandler": true   },   "operationTimeout": {     "CREATE": -1,     "UPDATE": -1,     "DELETE": -1,     "TEST": -1,     "SCRIPT_ON_CONNECTOR": -1,     "SCRIPT_ON_RESOURCE": -1,     "GET": -1,     "RESOLVEUSERNAME": -1,     "AUTHENTICATE": -1,     "SEARCH": -1,     "VALIDATE": -1,     "SYNC": -1,     "SCHEMA": -1   },   "configurationProperties": {     "customSensitiveConfiguration": null,     "createScriptFileName": "CreateScript.groovy",     "targetDirectory": null,     "customizerScriptFileName": "CustomizerScript.groovy",     "warningLevel": 1,     "authenticateScriptFileName": "AuthenticateScript.groovy",     "scriptExtensions": [       "groovy"     ],     "scriptOnResourceScriptFileName": "ScriptOnResourceScript.groovy",     "minimumRecompilationInterval": 100,     "deleteScriptFileName": "DeleteScript.groovy",     "scriptBaseClass": null,     "scriptRoots": [ "tools" ],     "customConfiguration": null,     "resolveUsernameScriptFileName": "ResolveUsernameScript.groovy",     "searchScriptFileName": "SearchScript.groovy",     "tolerance": 10,     "updateScriptFileName": "UpdateScript.groovy",     "debug": false,     "classpath": [],     "disabledGlobalASTTransformations": null,     "schemaScriptFileName": "SchemaScript.groovy",     "verbose": false,     "testScriptFileName": "TestScript.groovy",     "sourceEncoding": "UTF-8",     "syncScriptFileName": "SyncScript.groovy",     "recompileGroovySource": false,     "username": "username",     "password": "password",     "serviceAddress": "https://example.myshopify.com",     "proxyAddress": null,     "defaultAuthMethod": "BASIC",     "defaultContentType": "application/json",     "defaultRequestHeaders": null,     "OAuthTokenEndpoint": null,     "OAuthClientId": null,     "OAuthClientSecret": null,     "OAuthRefreshToken": null,     "OAuthScope": null,     "OAuthGrantType": "CLIENT_CREDENTIALS"   },       "objectTypes" : {         "__ACCOUNT__" : {             "$schema" : "http://json-schema.org/draft-03/schema",             "type" : "object",             "id" : "__ACCOUNT__",             "nativeType" : "__ACCOUNT__",             "properties" : {                 "givenName" : {                     "type" : "string",                     "nativeName" : "givenName",                     "nativeType" : "string"                 },                 "familyName" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "familyName",                     "nativeType" : "string"                 },                 "uid" : {                     "type" : "string",                     "required" : true,                     "nativeName" : "__NAME__",                     "nativeType" : "string",                     "flags" : [                         "NOT_UPDATEABLE"                     ]                 },                 "userName" : {                     "type" : "string",                     "nativeName" : "userName",                     "nativeType" : "string",                     "flags" : [                         "NOT_CREATABLE",                         "NOT_UPDATEABLE"                     ]                 },                 "emailAddress" : {                     "type" : "string",                     "nativeName" : "emailAddress",                     "nativeType" : "string"                 },                 "telephoneNumber" : {                     "type" : "string",                     "nativeName" : "telephoneNumber",                     "nativeType" : "string"                 },                 "displayName" : {                     "type" : "string",                     "nativeName" : "displayName",                     "nativeType" : "string",                     "required" : false                 },                 "created" : {                     "type" : "string",                     "nativeName" : "created",                     "nativeType" : "string",                     "required" : false                 },                 "lastModified" : {                     "type" : "string",                     "nativeName" : "lastModified",                     "nativeType" : "string",                     "required" : false                 },                 "marketing" : {                     "type" : "boolean",                     "nativeName" : "marketing",                     "nativeType" : "boolean",                     "required" : false                 },                 "totalspent" : {                     "type" : "string",                     "nativeName" : "totalspent",                     "nativeType" : "string",                     "required" : false                 },                 "note" : {                     "type" : "string",                     "nativeName" : "note",                     "nativeType" : "string",                     "required" : false                 }             }         }     },     "operationOptions" : {         "CREATE" : {             "objectFeatures" : {                 "__ACCOUNT__" : {                     "operationOptionInfo" : {                         "$schema" : "http://json-schema.org/draft-03/schema",                         "type" : "object",                         "properties" : { }                     }                 }             }         },         "UPDATE" : {             "objectFeatures" : {                 "__ACCOUNT__" : {                     "operationOptionInfo" : {                         "$schema" : "http://json-schema.org/draft-03/schema",                         "type" : "object",                         "properties" : { }                     }                 }             }         },         "DELETE" : {             "objectFeatures" : {                 "__ACCOUNT__" : {                     "operationOptionInfo" : {                         "$schema" : "http://json-schema.org/draft-03/schema",                         "type" : "object",                         "properties" : { }                     }                 }             }         },         "TEST" : {             "objectFeatures" : { }         },         "SCRIPT_ON_CONNECTOR" : {             "objectFeatures" : { }         },         "SCRIPT_ON_RESOURCE" : {             "objectFeatures" : { }         },         "GET" : {             "objectFeatures" : {                 "__ACCOUNT__" : {                     "operationOptionInfo" : {                         "$schema" : "http://json-schema.org/draft-03/schema",                         "type" : "object",                         "properties" : { }                     }                 }             }         },         "RESOLVEUSERNAME" : {             "objectFeatures" : {                 "__ACCOUNT__" : {                     "operationOptionInfo" : {                         "$schema" : "http://json-schema.org/draft-03/schema",                         "type" : "object",                         "properties" : { }                     }                 }             }         },         "AUTHENTICATE" : {             "objectFeatures" : {                 "__ACCOUNT__" : {                     "operationOptionInfo" : {                         "$schema" : "http://json-schema.org/draft-03/schema",                         "type" : "object",                         "properties" : { }                     }                 }             }         },         "SEARCH" : {             "objectFeatures" : {                 "__ACCOUNT__" : {                     "operationOptionInfo" : {                         "$schema" : "http://json-schema.org/draft-03/schema",                         "type" : "object",                         "properties" : { }                     }                 }             }         },         "VALIDATE" : {             "objectFeatures" : { }         },         "SYNC" : {             "objectFeatures" : {                 "__ACCOUNT__" : {                     "operationOptionInfo" : {                         "$schema" : "http://json-schema.org/draft-03/schema",                         "type" : "object",                         "properties" : { }                     }                 }             }         },         "SCHEMA" : {             "objectFeatures" : { }         }     } }'

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Identity Management > Configure > Connectors.

The Shopify connector is displayed in the Identity Management native console. 

 

Creating a Shopify app

  1. Log in to your Shopify store as the store owner.
  2. Generate the required credentials for connecting with your app by following the Shopify documentation. Use the following configuration for Identity Cloud:
    • App details: Enter the app name, for example, ForgeRock. Enter your email address for the Emergency developer email.
    • Admin API: Click Show inactive Admin API permissions, navigate to Customers and enable Read and Write.
  3. After you've saved the app, make a note of the API credentials for the private app you created. You'll need these when you complete the Scripted REST Connector configuration in Identity Cloud.

Linking the Scripted REST Connector to the Shopify customer API

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Identity Management > Configure > Connectors and select the Shopify connector.
  2. Enter the following details:
    • Service address: Enter your Shopify store URL.
    • Username: Enter the API key from your Shopify private app.
    • Password: Enter the API password from your Shopify private app.
 
  1. Click Save.

To validate the connector:

  1. Navigate to the Data tab to retrieve customers from Shopify. If you do not already have any users in Shopify this will be empty.
  2. In your Shopify store, add a new customer.
  3. In the Identity Cloud Admin UI, refresh the Data tab (Native Consoles > Identity Management > Configure > Connectors > Shopify connector > Data), and check that the new customer record is listed.
Note

It might take some time for the first record to appear, so you may need to refresh a few times. 

Configuring mappings to sync identities between Shopify and Identity Cloud 

You can sync in either direction between Identity Cloud and Shopify, so you may need to create two sync mappings depending on your use cases.

The steps below show you how to sync identities for the example schema provided in the Configuring a Scripted REST Connector section.

See Configure a Resource Mapping for further information on configuring mappings.

Sync Shopify users to Identity Cloud

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Identity Management > Create Mapping.
  2. Select the source (Shopify) and target resource (for example, Managed Alpha_User) and click Create mapping > Create.
  3. Click Quick Mapping to show all source and target properties.
  4. Drag the required source properties onto their corresponding target properties to create mappings, similar to the following example:
 
  1. Click Save.
  2. Sync marketing preferences by adding a JavaScript transformation script to the Preferences property:
    1. Navigate to Properties tab > Attributes Grid.
    2. Click Add property, select the preferences property and click Add.
    3. In the Transformation Script tab, add the following JavaScript transformation script, and click Save:result = {}; result.marketing = source.marketing; result.updates = false; result;
 
  1. Add a correlation query on the Mail attribute:
    1. Navigate to Association tab > Association Rules and select Correlation Queries.
    2. Click Add Correlation Query.
    3. Select Any of the following fields.
    4. Click the plus sign (+), select mail and click Submit.
 
  1. Set the mapping behavior to Default Actions:
    1. Select the Behaviors tab.
    2. Select Default Actions in the Current Policy drop-down and click Save.
  2. Click Reconcile to sync the identities.

Once the reconciliation is complete, in the Identity Cloud Admin UI, navigate to Identities > Manage > Alpha/Bravo Realm Users to check the Shopify accounts which have been sync'd to Identity Cloud.

Sync Identity Cloud users to Shopify

  1. In the Identity Cloud Admin UI, navigate to Native Consoles > Identity Management > Create Mapping.
  2. Select the source (for example, Managed Alpha_User) and target resource (Shopify) and click Create mapping > Create.
  3. Click Quick Mapping to show all source and target properties.
  4. Drag the required source properties onto their corresponding target properties to create mappings, similar to the following example:
 
  1. Click Save.
  2. Manually add a transformation mapping for the Marketing property:
    1. Navigate to Properties tab > Attributes Grid.
    2. Click Add property and select the marketing property, then click Add.
    3. In the Transformation Script tab, add the following JavaScript transformation script and click Save:source.preferences.marketing;
 
  1. Add a correlation query on the mail attribute:
    1. Navigate to Association tab > Association Rules and select Correlation Queries.
    2. Click Add Correlation Query.
    3. Select Any of the following fields.
    4. Click the plus sign (+), select emailAddress and click Submit.
 
  1. Change the mapping behavior from Read-Only to Default Actions:
    1. Select the Behaviors tab.
    2. Select Default Actions in the Currency policy drop-down and click Save.
  2. Click Reconcile to sync the identities.

You should now see user accounts from Identity Cloud in your Shopify dashboard.

See Also

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

RCS in Identity Cloud

Identity Cloud or IDM fail to connect to the Remote Connector Server (RCS) with a Failed to validate and load script error


How do I run a Remote Connector Server (RCS) as a Service?

The purpose of this article is to provide instructions on running the RCS as a service, which allows you to stop and start the RCS using systemd if you are using a Linux® system.

Overview

The following instructions were tested on Ubuntu 20.04 LTS but they should work (with no/minimal changes) on any Linux distribution using systemd.

These instructions assume you have unpacked the RCS package into the /opt directory and left the unpacked directory name unchanged (openicf). If you have any variations to these path locations, you must update the service file accordingly when following the instructions in Step 2.

Configuring RCS as a service

  1. Create a service file (called rcs.service) in the /etc/systemd/system directory, for example:$ sudo vim /etc/systemd/system/rcs.service
  2. Add the following content to this file, update as needed and save: [Unit] SourcePath=/opt/openicf/bin Description=ForgeRock Remote Connector Server (systemd init) After=network.target Conflicts=shutdown.target [Service] Type=simple Restart=always RestartSec=5sec IgnoreSIGPIPE=no KillMode=process Environment="OPENICF_OPTS=-Xmx1024m" ExecStart=/opt/openicf/bin/ConnectorServer.sh /run [Install] WantedBy=multi-user.target
  3. Make the new service launch on startup by running the following command:$ sudo systemctl enable rcs.service
  4. Check the service is enabled:$ systemctl is-enabled rcs.serviceThis command simply returns enabled or disabled as appropriate.

Starting, stopping and restarting the RCS service

Once you have configured RCS as a service and checked it is enabled, you can use the following commands to start, stop and restart the RCS service:

  • Start:$ sudo systemctl start rcs.service
  • Stop:$ sudo systemctl stop rcs.service
  • Restart:$ sudo systemctl restart rcs.service

Checking the service status

You can check that the RCS service has started or stopped as expected using the following command:$ systemctl status rcs.service

This command will return the service state and the first few entries in the log file. For example, the status command’s output will look similar to the following, where systemd messages indicate that the init script has started and the RCS service is running:

● rcs.service - ForgeRock Remote Connector Server (systemd init)   Loaded: loaded (/opt/openicf/bin; enabled; vendor preset: enabled)    Active: active (running) since Mon 2021-03-08 12:45:16 GMT; 22s ago  Main PID: 3080 (java)     Tasks: 35 (limit: 4684)    CGroup: /system.slice/rcs.service            └─3080 java -Xmx512m -server -classpath /opt/openicf/lib/framework/*:/opt/openicf/lib/framework/ org.forgerock.openicf.framework.server.Main -run -properties /opt/openicf/conf/ConnectorServer.properties Mar 08 12:45:29 forgerock-VirtualBox ConnectorServer.sh[3080]: Mar 08, 2021 12:45:29 pm INFO  o.f.o.f.c.ClientRemoteConnectorInfoManager: privateConnections size: 0; privateTCPConnections size 0. Mar 08 12:45:29 forgerock-VirtualBox ConnectorServer.sh[3080]: Mar 08, 2021 12:45:29 pm INFO  o.f.o.f.c.ClientRemoteConnectorInfoManager: Entering connection housekeeping... 0 active WebSocket(s), 2 available permits, 3 permitted permits Mar 08 12:45:29 forgerock-VirtualBox ConnectorServer.sh[3080]: Mar 08, 2021 12:45:29 pm INFO  o.f.o.f.c.ClientRemoteConnectorInfoManager: 0 active WebSocket(s), 2 remaining permits

See Also

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

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

Sync Identities


How do I enable debug logging and log rotation for the Remote Connector Server (RCS)?

The purpose of this article is to provide information on enabling debug logging and log rotation for the Java® RCS.

Overview

By default, logging is not enabled for the Java RCS. Additionally, log files are not set to rotate by default, which means they will grow in size indefinitely when logging is enabled.

If you want to enable logging for the RCS, it is strongly recommended that you also configure the log files to rotate as described in this article.

Debug Logging

You can enable debug logging as follows:

  1. Edit the logback.xml file (which is located in the /path/to/openicf/lib/framework/ directory) and uncomment the following section: <logger name="org.identityconnectors.framework.impl.api.LoggingProxy" level="DEBUG" additivity="false">         <appender-ref ref="TRACE-FILE"/>     </logger>
  2. Restart the RCS:$ /path/to/openicf/bin/ConnectorServer.sh /runThe debug logs will be written to the ConnectorServer.log (located in the /path/to/openicf/logs directory).

Rotating Log Files

You can configure the RCS to rotate log files as follows:

  1. Edit the logback.xml file and replace the following section (appender class: ch.qos.logback.core.FileAppender for the ConnectorServer.log file): <appender name="SERVER-FILE" class="ch.qos.logback.core.FileAppender">         <file>logs/ConnectorServer.log</file>         <append>true</append>         <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">             <fileNamePattern>logs/ConnectorServer-%d{yyyyMMdd}.log</fileNamePattern>         </rollingPolicy>         <encoder>             <pattern>%date{"MMM dd, yyyy h:mm:ss a"} %-5level %logger{35}: %msg %n</pattern>         </encoder>     </appender>With this section:<appender name="SERVER-FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">        <file>logs/ConnectorServer.log</file>         <append>true</append>         <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">             <fileNamePattern>logs/ConnectorServer-%d{yyyyMMdd}.log</fileNamePattern>             <!-- keep 30 days of logs capped at 1GB total size -->             <maxHistory>30</maxHistory>             <totalSizeCap>1GB</totalSizeCap>         </rollingPolicy>         <encoder>             <pattern>%date{"MMM dd, yyyy h:mm:ss a"} %-5level %logger{35}: %msg %n</pattern>         </encoder>     </appender>Where:
    • The appender class is changed to ch.qos.logback.core.rolling.RollingFileAppender to rotate the logs.
    • The maxHistory and totalSizeCap properties are added to ensure old logs are removed. This example configures them so that 30 days of logs are kept, capped at 1GB in size, but you can set them as needed for your environment.
  2. Restart the RCS:$ /path/to/openicf/bin/ConnectorServer.sh /run

See Also

RCS in Identity Cloud

Related Issue Tracker IDs

OPENICF-1638 (RCS logback.xml should be configured for rolling log files with max age/size over a single ever growing file by default)


Known Issues


Identity Cloud or IDM fail to connect to the Remote Connector Server (RCS) with a Failed to validate and load script error

The purpose of this article is to provide assistance if you see "Failed to validate and load script" errors when Identity Cloud or IDM fail to connect to the RCS. This issue only occurs when you are using scripted connectors.

Symptoms

Identity Cloud or IDM fail to connect to the RCS and you see errors similar to the following in the RCS logs:2021-09-22 10:22:03,537 ERROR o.f.o.c.g.ScriptedConfiguration: Failed to validate and load script: CreateScript.groovy Method: validateScript org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed: IO Exception attempting to load global transforms:/tmp/bundle-1192785746/lib/groovy-3.0.7.jar

See How do I enable debug logging and log rotation for the Remote Connector Server (RCS)? for further information on debugging.

In IDM, you will also see a similar error occurring:WARNING: Failure to activate connector. org.codehaus.groovy.control.MultipleCompilationErrorsException: startup failed: IO Exception attempting to load global transforms:/tmp/bundle-1192785746/lib/groovy-3.0.7.jar

Recent Changes

Configured a scripted connector for the RCS.

Causes

When the RCS initially starts up, it creates temporary connector bundle files in the JVM temp directory (/tmp by default on Unix® and Linux® systems). These files are required to compile scripted connectors.

When Identity Cloud or IDM attempts to connect to the RCS, the RCS uses these temporary files to compile the scripted connectors being used. Assuming they exist, the connection proceeds and everything functions as expected. If these files cannot be found, Identity Cloud or IDM will fail to connect with the “Failed to validate and load script” error seen above.

Some operating systems have a watcher process that deletes files from the temp directory automatically after a certain period of time. If this happens, the RCS will continue to operate without any errors but if something subsequently causes Identity Cloud or IDM to try to reconnect to the RCS (for example, a promotion in Identity Cloud or restarting IDM), the connection will fail because the temporary connector bundle files are missing.

Solution

This issue can be resolved by creating a dedicated temp directory for the temporary connector bundle files so they're not deleted by any watcher processes. You can do this as follows:

  1. Create a temp directory for the bundle files, for example:$ cd /path/to/openicf $ mkdir bundle_tmp
  2. If you are running RCS as a service: edit the service file (for example, rcs.service in the /etc/systemd/system directory) and update the Environment line to include the temp directory you created in step 1:-Djava.io.tmpdir=/path/to/openicf/bundle_tmpThe Environment line should now look similar to this:Environment="OPENICF_OPTS=-Xmx1024m -Djava.io.tmpdir=/path/to/openicf/bundle_tmp"
  3. Restart the RCS as follows depending on whether you are running it as a service or not; if you are not running it as a service, you will need to set the temp directory when you start it:
    • RCS as a service:$ sudo systemctl restart rcs.service
    • RCS not as a service and deployed on Unix and Linux systems:$ cd /path/to/openicf/bin $ export OPENICF_OPTS="-Djava.io.tmpdir=/path/to/openicf/bundle_tmp" $ ./ConnectorServer.sh /run
    • RCS not as a service and deployed on Microsoft® Windows® systems:C:\> cd \path\to\openicf\bin C:\path\to\openicf\bin> set OPENICF_OPTS=-Djava.io.tmpdir=/path/to/openicf/bundle_tmp  C:\path\to\openicf\bin> ConnectorServer.bat /run
  4. Verify this change has taken effect by checking that the bundle files have been created under the new temp directory (/path/to/openicf/bundle_tmp) after restarting the RCS.

See Also

RCS in Identity Cloud


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.

This content has been optimized for printing.