Create a connector configuration over REST

Create a connector configuration over REST when the connector you want to use is not supported in the Identity Cloud admin UI, or if you want to use a scripted connector.

Follow the instructions on this page to:

List available connectors.
Generate the core configuration.
Send your connector configuration over REST to Identity Cloud.

Before you begin

You’ll need to know the location of your individual operations script files. These are the scripts that run CRUD operations your users access in Identity Cloud. You’ll also need to know your service URI.
Get a user access token.
The access token must include:
- IDM admin privileges
- The fr:idm:* scope

Set an environment variable with the token value.

Example:

export TOKEN="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJkNWE4NDVjMy03MjFh
LTQzN2QtYjIyZi04ZjNlNzUyNDExNWIiLCJjdHMiOiJPQVVUSDJfR1JBTlRfU0VUIiwiYXV0aF9sZXZ
lbCI6MCwiYXVkaXRUcmFja2luZ0lkIjoiYjU4M2Q2NGUtM2VlYi00M2Y5LWI5ZTctZDM4MDI4MDQyYW
JmLTY0MyIsImlzcyI6Imh0dHBzOi8vb3BlbmFtLWNhcmlhZ2EtMDUuZm9yZ2VibG9ja3MuY29tL2FtL"

Your remote connector server must be up and running.
See Connecting Identities.

Getting a user access token

There are many different ways to get a user access token. One way is to use the Identity Cloud Postman collection.

Follow the instructions for getting started with the Postman collection.
In the Postman collection, click Prerequisites.
To create an admin user and set scope, complete Steps 1 through 3.

Show me where
To generate a token, complete any one of flows in the OAuth 2.0 directory.

Show me where

1 - List the available connectors

Run a command like this example, replacing <tenant> with your tenant name:

$ curl \
  -H 'authorization: Bearer '"$TOKEN" \
  --header "Accept-API-Version: resource=1.0" \
  --request POST \
  'https://<tenant-env-fqdn>/openidm/system?_action=availableConnectors'

Your connector server returns a list of available connectors.

Example: Generated list of connectors

{
  "connectorRef": [
    {
      "displayName": "ServiceNow Connector",
      "bundleVersion": "1.5.18.0-RC1",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.servicenow-connector",
      "connectorName": "org.forgerock.openicf.connectors.servicenow.ServiceNowConnector"
    },
    {
      "displayName": "Salesforce Connector",
      "bundleVersion": "1.5.18.0-RC1",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.salesforce-connector",
      "connectorName": "org.forgerock.openicf.connectors.salesforce.SalesforceConnector"
    },
    {
      "displayName": "Marketo Connector",
      "bundleVersion": "1.5.18.0-RC1",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.marketo-connector",
      "connectorName": "org.forgerock.openicf.connectors.marketo.MarketoConnector"
    },
    {
      "displayName": "Adobe Marketing Cloud Connector",
      "bundleVersion": "1.5.18.0-RC1",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.adobecm-connector",
      "connectorName": "org.forgerock.openicf.acm.ACMConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "SSH Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.ssh-connector",
      "connectorName": "org.forgerock.openicf.connectors.ssh.SSHConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "Scripted SQL Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.scriptedsql-connector",
      "connectorName": "org.forgerock.openicf.connectors.scriptedsql.ScriptedSQLConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "Scripted REST Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector",
      "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "Scim Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.scim-connector",
      "connectorName": "org.forgerock.openicf.connectors.scim.ScimConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "LDAP Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.ldap-connector",
      "connectorName": "org.identityconnectors.ldap.LdapConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "Kerberos Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.kerberos-connector",
      "connectorName": "org.forgerock.openicf.connectors.kerberos.KerberosConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "Scripted Poolable Groovy Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedPoolableConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "Scripted Groovy Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.groovy-connector",
      "connectorName": "org.forgerock.openicf.connectors.groovy.ScriptedConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "Database Table Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.databasetable-connector",
      "connectorName": "org.identityconnectors.databasetable.DatabaseTableConnector"
    },
    {
      "connectorHostRef": "connectorserver1",
      "displayName": "CSV File Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
      "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector"
    }
  ]
}

In the list generated, find the connector you want to use and copy its JSON configuration object.

2 - Generate the core configuration

Run a REST request like this example. Replace the values in --data-binary with your own configuration details:

Replace these variables with your own values: <tenant> and <connector-server-name>.

Paste the JSON configuration object you copied from the generated list into the body of the REST command. This example uses the Scripted REST Connector.

$ curl 'https://<tenant-env-fqdn>/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": "<connector-server-name>",
      "displayName": "Scripted REST Connector",
      "bundleVersion": "1.5.18.0",
      "systemType": "provisioner.openicf",
      "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector",
      "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"
    }
  }'

After you run the command, your connector server returns a core configuration—a template—for the scripted REST connector.

Example: Generating the core configuration template

$ curl 'https://<tenant-env-fqdn>/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": "connectorserver1",
        "displayName": "Scripted REST Connector",
        "bundleVersion": "1.5.18.0",
        "systemType": "provisioner.openicf",
        "bundleName": "org.forgerock.openicf.connectors.scriptedrest-connector",
        "connectorName": "org.forgerock.openicf.connectors.scriptedrest.ScriptedRESTConnector"
      }
   }' | jq .
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2256  100  1879  100   377  19989   4010 --:--:-- --:--:-- --:--:-- 24000
{
  "connectorRef": {
    "connectorHostRef": "connectorserver1",
    "displayName": "Scripted REST Connector",
    "bundleVersion": "1.5.18.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": null,
    "targetDirectory": null,
    "customizerScriptFileName": null,
    "warningLevel": 1,
    "authenticateScriptFileName": null,
    "scriptExtensions": [
      "groovy"
    ],
    "scriptOnResourceScriptFileName": null,
    "minimumRecompilationInterval": 100,
    "deleteScriptFileName": null,
    "scriptBaseClass": null,
    "scriptRoots": null,
    "customConfiguration": null,
    "resolveUsernameScriptFileName": null,
    "searchScriptFileName": null,
    "tolerance": 10,
    "updateScriptFileName": null,
    "debug": false,
    "classpath": [],
    "disabledGlobalASTTransformations": null,
    "schemaScriptFileName": null,
    "verbose": false,
    "testScriptFileName": null,
    "sourceEncoding": "UTF-8",
    "syncScriptFileName": null,
    "recompileGroovySource": false,
    "username": null,
    "password": null,
    "serviceAddress": null,
    "proxyAddress": null,
    "defaultAuthMethod": "BASIC",
    "defaultContentType": "application/json",
    "defaultRequestHeaders": null,
    "OAuthTokenEndpoint": null,
    "OAuthClientId": null,
    "OAuthClientSecret": null,
    "OAuthRefreshToken": null,
    "OAuthScope": null,
    "OAuthGrantType": "CLIENT_CREDENTIALS"
  }
}

The core configuration template is not yet functional. It doesn’t contain the required configurationProperties values. Also, it doesn’t contain the names or locations of the individual script files to use for the CRUD operations.

3 - Send the connector configuration to Identity Cloud

Copy the core configuration template into a PUT request like this example.
At minimum, replace the values for the required properties: scriptRoots and seviceAddress

For descriptions of all the configuration properties, refer to Configuration properties.

Run a REST command to send your customized connector configuration to Identity Cloud.
In this example:

<tenant> is replaced with mytenant
The target connector configuration will be named myscriptedconnector in Identity Cloud.

<connector-server-name> is replaced with connectorserver1

$ curl 'https://<tenant-env-fqdn>/openidm/config/provisioner.openicf/myscriptedconnector' \
  -X PUT \
  -H 'authorization: Bearer '"$TOKEN" \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/javascript, /; q=0.01' \
  --data-binary `
{
  "connectorRef": {
    "connectorHostRef": "connectorserver1",
    "displayName": "Scripted REST Connector",
    "bundleVersion": "1.5.18.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": null,
    "targetDirectory": null,
    "customizerScriptFileName": null,
    "warningLevel": 1,
    "authenticateScriptFileName": null,
    "scriptExtensions": [
      "groovy"
    ],
    "scriptOnResourceScriptFileName": null,
    "minimumRecompilationInterval": 100,
    "deleteScriptFileName": null,
    "scriptBaseClass": null,
    "scriptRoots": "/path/to/openicf/scripts",
    "customConfiguration": null,
    "resolveUsernameScriptFileName": null,
    "searchScriptFileName": null,
    "tolerance": 10,
    "updateScriptFileName": null,
    "debug": false,
    "classpath": [],
    "disabledGlobalASTTransformations": null,
    "schemaScriptFileName": null,
    "verbose": false,
    "testScriptFileName": null,
    "sourceEncoding": "UTF-8",
    "syncScriptFileName": null,
    "recompileGroovySource": false,
    "username": null,
    "password": null,
    "serviceAddress": http://myservice.com/api,
    "proxyAddress": null,
    "defaultAuthMethod": "BASIC",
    "defaultContentType": "application/json",
    "defaultRequestHeaders": null,
    "OAuthTokenEndpoint": null,
    "OAuthClientId": null,
    "OAuthClientSecret": null,
    "OAuthRefreshToken": null,
    "OAuthScope": null,
    "OAuthGrantType": "CLIENT_CREDENTIALS"
  }
}

If there were no errors, you should see your connector in the IDM native console.