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

Last updated Jan 17, 2023

The purpose of this article is to provide information on setting up a Scripted REST connector using the RCS with ForgeRock Identity Cloud.

Overview

This article provides information on how to set up a Scripted REST connector using the RCS with Identity Cloud.

With the Scripted REST connector, you can interact with any REST API, using Groovy scripts for Identity Connector Framework (ICF) operations. This allows you to develop REST-based connectors for in-house applications or cloud applications not yet supported in the standard set of Identity Cloud connectors. See Scripted REST connector for further information.

Steps involved:

Set up the Remote Connector Server (RCS)
Configure a Scripted REST Connector

Prerequisites

You have a working Identity Cloud tenant.
You have created Groovy scripts for each operation you want the connector to perform (create, read, update, delete, authenticate, and so on). ForgeRock provides sample scripts for each operation, which you can download and modify as needed.

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:

Register a remote server
Download the remote server
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, go to Identities > Connect and check RCS server status is 'Connected’.

Add the Groovy scripts to the RCS

Add your Scripted REST connector Groovy scripts to a directory in your RCS installation. For example:

Create a scripts directory in /path/to/openicf.
Add your Groovy scripts to the /path/to/openicf/scripts directory.

Configuring a Scripted REST connector

You'll configure the Scripted REST connector using REST calls, as outlined in Configure connectors over REST.

Before you can configure the Scripted REST connector, you will need an access token to authenticate to the Identity Cloud REST API. See Authenticate to Identity Cloud REST API with access token for further information.

Configure the Scripted REST connector as follows:

Run the following command to list the available connectors, replacing <tenant-env-fqdn> with your Identity Cloud tenant name and <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API. $ curl \ --request POST 'https://<tenant-env-fqdn>/openidm/system?_action=availableConnectors' \ --header 'authorization: Bearer <access-token> \ --header 'Accept-API-Version: resource=1.0'

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.9", "systemType": "provisioner.openicf", "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector", "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector" }

Run the following command to generate the core configuration template, replacing <tenant-env-fqdn> with your Identity Cloud tenant name and <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API. In the connectorRef section, make sure you include your Scripted REST connector details generated in the previous step, for example:$ curl 'https://<tenant-env-fqdn>/openidm/system?_action=createCoreConfig' \ --header 'authorization: Bearer <access-token> \ --header 'content-type: application/json' \ --header 'accept: application/json, text/javascript, */*; q=0.01' \ --data-binary '{"connectorRef" : { "connectorHostRef": "rcs", "displayName": "Scripted REST Connector", "bundleVersion": "1.5.20.9", "systemType": "provisioner.openicf", "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector", "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector" } }'The resulting core configuration template should look similar to this. You'll use this template to create the configuration for your scripted REST connection. "connectorRef": { "connectorHostRef": "rcs", "displayName": "Scripted REST Connector", "bundleVersion": "1.5.20.9", "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": "/path/to/openicf/scripts", "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.com", "proxyAddress": null, "defaultAuthMethod": "BASIC", "defaultContentType": "application/json", "defaultRequestHeaders": null, "OAuthTokenEndpoint": null, "OAuthClientId": null, "OAuthClientSecret": null, "OAuthRefreshToken": null, "OAuthScope": null, "OAuthGrantType": "CLIENT_CREDENTIALS" },

The template does not include all the required values in the configurationProperties section for the target system, so you'll need to make some changes, as described in the next step.

Run a PUT command similar to the following example, to send the connector configuration to Identity Cloud.
- Replace <tenant-env-fqdn> with the name of your Identity Cloud tenant, <connector-name> with the name of the scripted connector and <access-token> with the access token you obtained when you authenticated to the Identity Cloud REST API.
- In the configurationProperties section, at the minimum, replace:
  - scriptRoots with the path to the directory that contains the Groovy scripts.
  - serviceAddress with the URL or URI of the connected service.

See Configuration properties for information on all the available configuration properties.

The following example is for a Shopify connector. The request includes a schema, which includes personal details, marketing preferences, total spent, and notes on the customer record.

$ curl --include --location --request PUT 'https://<tenant-env-fqdn>/openidm/config/provisioner.openicf/<connector-name>' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <access-token> \ --data-raw '{ "connectorRef": { "connectorHostRef": "rcs", "displayName": "Scripted REST Connector", "bundleVersion": "1.5.20.9", "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": "/path/to/openicf/scripts", "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" : { } } } }'

If there are no errors, the connector is created in Identity Cloud.

Verify the connector

To verify that the connector is available:

In the Identity Cloud admin UI, go to Native Consoles > Identity Management > Configure > Connectors.

The Scripted REST Connector should be displayed, similar to this example Shopify connector: