Remote connector configuration

Identity Cloud also provides many remote connectors for continuous, two-way synchronization with external data stores that reside on premises, in a private cloud, or in a public cloud.

Remote connectors run on a remote connector server (RCS), on the same host as the external data store. They communicate inbound with your Identity Cloud tenant.

Running connectors remotely requires the following high-level steps:

Install a Java RCS on your on-prem server.
Many connectors are bundled with the RCS itself. If the connector you want to use is not bundled with the RCS, download it from the ForgeRock BackStage download site, and put the .jar file on your remote server, in the /path/to/openicf/connectors/ directory.
Configure Identity Cloud to connect to the RCS.

Install the Java Remote Connector Server (RCS)

ForgeRock Identity Cloud supports the Java RCS. The system on which you install the Java RCS must run JRE version 11, or later. Disk space and memory requirements will depend on the number of connectors you are using, and the volume of traffic through the RCS.

Set Up a Java RCS

Install a Java RCS on Unix/Linux

Download and extract the Java RCS from the ForgeRock BackStage download site.
Change to the openicf directory:
```
cd /path/to/openicf
```
Review the ConnectorServer.properties file in the /path/to/openicf/conf directory, and adjust it to suit your deployment. For a complete list of properties in that file, see RCS Properties.
Start the Java RCS:
```
/path/to/openicf/bin/ConnectorServer.sh /run
```
The RCS is now running, and listening on port 8759, by default.

Log files are available in the /path/to/openicf/logs directory.
```
ls logs/
Connector.log  ConnectorServer.log  ConnectorServerTrace.log
```
To stop the Java RCS, press CTRL + C, or q in the terminal where you started the server.

Install a Java RCS on Windows

Download and extract the Java RCS from the ForgeRock BackStage download site.
In a Command Prompt window, change to the openicf directory:
```
C:\> cd C:\path\to\openicf
```
Review the ConnectorServer.properties file in the \path\to\openicf\conf directory, and adjust it to suit your deployment. For a complete list of properties in that file, see RCS Propterties.
You can either run the Java RCS as a Windows service, or start and stop it from the command line:
1. To install the Java RCS as a Windows service, run the following command:
  c:\path\to\openicf> bin\ConnectorServer.bat /install
  If you install the RCS as a Windows service, you can use the Microsoft Services Console to start, stop, and restart the service. The Java Connector Service is named OpenICFConnectorServerJava.
  
  To uninstall the Java RCS as a Windows service, run the following command:
  c:\path\to\openicf> bin\ConnectorServer.bat /uninstall
2. To start the Java RCS from the command line, enter the following command:
  c:\path\to\openicf> bin\ConnectorServer.bat /run
The RCS is now running, and listening on port 8759, by default.

Log files are available in the \path\to\openicf\logs directory.
To stop the Java RCS, press ^ + C.

RCS connectors use the following configuration properties:

RCS Properties

This table shows the complete list of RCS configuration properties. Note that all properties are prefixed with connectorserver. in the configuration file. The prefixes are not shown here so that the table is easier to read:

Property RCS Mode (Server or Client) Description Example

connectorServerName

Client

Name of the remote connector client. This name is used to identify the remote connector server in the list of connector reference objects. The name must be lower case alphanumeric characters (^[a-z0-9]*$), and must match the name property in the provisioner.openicf.connectorinfoprovider.json file on your Identity Cloud server.

rcs1

url

Client

URL of the server on which Identity Cloud runs.

wss://openidm.example.com:8443/openicf ^[1]

1. Note the wss (WebSocket) transport protocol and the openicf endpoint.

hostId

Client

Unique identifier for the RCS.

MY_UNIQUE_RCS_HOST_ID

proxyHost

Client

Proxy server host.

proxyPort

Client

Proxy server port number.

proxyPrincipal

Client

Proxy server principal.

proxyPassword

Client

Proxy server password.

housekeepingInterval

Client

WebSocket connections housekeeping interval, in seconds.

groupCheckInterval

Client

WebSocket groups check interval, in seconds.

900

webSocketConnections

Client

Number of WebSocket connections to open.

connectionTtl

Client

Time to live of a WebSocket connection, in seconds.

newConnectionsInterval

Client

Time (in seconds) before a new connection can be established.

tokenEndpoint

Client

Token endpoint from which to retrieve the access token, if you are using OAuth2 to authenticate against AM.

https://am.example.com/am/oauth2/realms/root/access_token

scope

Client

OAuth2 token scope, if you are using OAuth2 to authenticate against AM.

fr:idm:*

clientId

Client

OAuth2 Client ID for which to request an access token.

connectorServer

If the RCS is authenticating against AM, you must update your Identity Cloud authentication configuration (in conf/authentication.json). Add a user mapping for this client ID in the rsFilter authentication module configuration. For more information, see Authenticate through AM.

clientSecret

Client

OAuth2 Client Secret.

openidm

pingPongInterval

Both

WebSocket Ping/Pong interval, in seconds. The purpose of the ping is to keep connections alive (for firewalls or load balancers that honor connections in use). If your firewall or load balancer does not honor connections in use (that is, connections are timed out, regardless of their usage), the ping has no effect and you should disable it. Set this property to 0 to disable the ping.

300

trustStoreFile

Both

The RCS truststore file. You do not need to set this property if the RCS certificate is a CA-signed certificate.

security/truststore.pkcs12

trustStoreType

Both

The RCS truststore type. You do not need to set this property if the RCS certificate is a CA-signed certificate.

PKCS12

trustStorePass

Both

The RCS truststore password. You do not need to set this property if the RCS certificate is a CA-signed certificate.

changeit

keyStoreFile

Both

The RCS keystore file. You do not need to set this property if the RCS certificate is a CA-signed certificate.

security/keyStore.pkcs12

keyStoreType

Both

The RCS keystore type. You do not need to set this property if the RCS certificate is a CA-signed certificate.

PKCS12

keyStorePass

Both

The RCS keystore password. You do not need to set this property if the RCS certificate is a CA-signed certificate.

changeit

keyPass

Both

The Identity Cloud certificate password. You do not need to set this property if the RCS certificate is a CA-signed certificate.

changeit

libDir

Both

Directory on the RCS host in which connector library file dependencies are located (relative to /path/to/openicf/ ).

lib

bundleDir

Both

Directory on the RCS host in which connector .jar files are located (relative to /path/to/openicf/).

connectors

loggerClass

Both

The RCS logger class.

org.forgerock.openicf.common.logging.slf4j.SLF4JLog

principal

Both

Principal to authenticate to the RCS. This property is not used in Identity Cloud.

anonymous

password

Both

Password to authenticate to the RCS. This property is not used in Identity Cloud.

changeit

useSSL

Server

Whether the connection between Identity Cloud and the RCS should be over SSL.

false/true

port

Server

Port on which the RCS listens for the connection from Identity Cloud.

8759

Certain configuration properties are dependent on the RCS mode. For more information, see Configure a Remote Connector Server (RCS).

Sample connectorserver.properties file for client mode

connectorserver.url=wss://my-tenant.forgeblocks.com:8443/openicf
connectorserver.connectorServerName=myConnectorServer
connectorserver.hostId=MY_UNIQUE_RCS_HOST_ID
connectorserver.pingPongInterval=60
connectorserver.housekeepingInterval=20
connectorserver.groupCheckInterval=900
connectorserver.webSocketConnections=3
connectorserver.maxWebSocketConnections=4
connectorserver.connectionTtl=3000
connectorserver.newConnectionsInterval=10
connectorserver.tokenEndpoint=https://my-tenant.forgeblocks.com/am/oauth2/realms/root/realms/alpha/access_token
connectorserver.clientId=my-client-id
connectorserver.clientSecret=my-client-secret
connectorserver.trustStoreFile=security/truststore.pkcs12
connectorserver.trustStoreType=PKCS12
connectorserver.trustStorePass=changeit
connectorserver.keyStoreFile=security/keyStore.pkcs12
connectorserver.keyStoreType=PKCS12
connectorserver.keyStorePass=changeit
connectorserver.keyPass=changeit
connectorserver.scope=fr:idm:*
connectorserver.bundleDir=connectors
connectorserver.libDir=lib
connectorserver.loggerClass=org.forgerock.openicf.common.logging.slf4j.SLF4JLog

Install connector dependencies

In most cases, ICF connectors come bundled with all third party libraries needed to run. In some cases, however, you’ll need to download certain libraries (for example, the Database Table connector needs the appropriate JDBC driver for the database you are targeting). For local connectors, place these libraries in the /path/to/openidm/lib/ directory. For remote connectors, place them in the /path/to/openicf/lib/ directory on the RCS.

The following table lists the connector dependencies and indicates which ones must be downloaded:

Dependencies for bundled connectors

Dependencies for bundled connectors
Database Table Connector	No external dependencies. However, you must include the JDBC driver for the database that you are targeting in the `/path/to/openidm/lib/` directory.
DocuSign Connector	`lib/java-jwt-3.4.0.jar`
PeopleSoft Connector	`lib/psft.jar` `lib/psjoa.jar`

Database Table Connector

No external dependencies. However, you must include the JDBC driver for the database that you are targeting in the /path/to/openidm/lib/ directory.

DocuSign Connector

lib/java-jwt-3.4.0.jar

PeopleSoft Connector

lib/psft.jar

lib/psjoa.jar

Configure a Remote Connector Server (RCS) in client mode

In client mode, RCS initiates the connection with a server. The following diagram shows an RCS in client mode:

Configure RCS in client mode

To generate the core configuration, use the createConnectorServerCoreConfig action on the system endpoint. Include at least the RCS type (remoteConnectorClient) and the systemType in the JSON payload. The systemType is always provisioner.openicf, regardless of the RCS type:

Create a Core RCS Configuration (Client Mode)

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "type": "remoteConnectorClient",
  "systemType": "provisioner.openicf"
}' \
"http://<tenant-env-fqdn>/openidm/system?_action=createConnectorServerCoreConfig"
{
  "displayName": "",
  "name": "",
  "enabled": true,
  "useSSL": false
}

Identity Cloud returns the basic configuration properties for an RCS in client mode. The configuration that is returned is not functional. It does not contain the required configuration property values, such as the name of the RCS.

Use the output returned in the previous example to create your complete RCS configuration. Specify at least the name of the RCS, and use a PUT request on the config endpoint. Note that this step creates an RCS configuration on Identity Cloud. The values of these properties must match the RCS configuration, specified in the ConnectorServer.properties file on the RCS:

Create a New RCS Configuration (Client Mode)

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorClients": [
    {
      "displayName": "On premise 1",
      "name": "onprem",
      "enabled": true
    }
  ]
}' \
"http://<tenant-env-fqdn>/openidm/config/provisioner.openicf.connectorinfoprovider"
{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorClients": [
    {
      "displayName": "On premise 1",
      "name": "onprem",
      "enabled": true
    }
  ]
}

Configure failover between RCS servers

For failover purposes, you can configure a group of RCSs, in either server or client mode. Failover is particularly important when you configure an RCS in client mode because Identity Cloud has no way of knowing whether the RCS is available.

To prevent the RCS from being a single point of failure, you can specify a list of RCS servers that the connector can target. To set up a failover configuration, you create either a remoteConnectorServersGroup or a remoteConnectorClientsGroup and list the RCS servers. The connector attempts to contact the first RCS in the list. If that RCS is down, it proceeds to the next RCS.

Configure Failover For RCS Servers in Client Mode

This example configures a remoteConnectorClientsGroup that lists two remote RCS servers, on hosts remote-host-1 and remote-host-2. The RCS servers are listed by their name property. You can configure multiple groups and multiple servers per group.

First, generate the core configuration to obtain the required properties:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "type" : "remoteConnectorClientsGroup",
  "systemType" : "provisioner.openicf"
}' \
"http://<tenant-env-fqdn>/openidm/system?_action=createConnectorServerCoreConfig"
{
   "displayName": "",
   "name": "",
   "serversList": [],
   "algorithm": "failover"
 }

Use the output returned in the previous example to create your RCS group configuration. Use a PUT request on the config endpoint:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorClients": [
    {
      "type": "remoteConnectorClientsGroup",
      "displayName": ".NET Failover Group",
      "name" : "dotnet-ha",
      "algorithm" : "failover",
      "serversList" : [
        {"name": "remote-host-1"},
        {"name": "remote-host-2"}
      ]
    }
  ]
}' \
"http://<tenant-env-fqdn>/openidm/config/provisioner.openicf.connectorinfoprovider"
{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorClients": [
    {
      "type": "remoteConnectorClientsGroup",
      "displayName": ".NET Failover Group",
      "name": "dotnet-ha",
      "algorithm": "failover",
      "serversList": [
        {
          "name": "remote-host-1"
        },
        {
          "name": "remote-host-2"
        }
      ]
    }
  ]
}

The algorithm can be either failover or roundrobin. If the algorithm is failover, requests are always sent to the first RCS in the list, unless it is unavailable; in which case, requests are sent to the next RCS in the list. If the algorithm is roundrobin, requests are distributed equally between the RCS servers in the list, in the order in which they are received.

Your connector configuration (provisioner.openicf-connector-name.json ) references the RCS group, rather than a single RCS.

Secure the connection to the RCS with SSL

In client mode, the RCS initiates the connection to Identity Cloud. Identity Cloud sends its certificate during the SSL handshake. If you are using the Identity Cloud self-signed certificate, you must import the certificate into the RCS truststore.

If you are using TLS Mutual Authentication, the RCS needs a public/private key pair and a certificate. Identity Cloud requests the certificate from the RCS during the SSL handshake.

Configure the RCS For SSL

On the RCS, edit the conf/ConnectorServer.properties file to specify a secure connection between Identity Cloud and the RCS:

RCS in client mode

Connection security is determined by the value of the connectorserver.url property. Use the wss protocol to establish a WebSocket over an encrypted TLS connection; for example, wss://my-tenant.forgeblocks.com/openicf.

The connectorserver.useSSL property is not used in client mode.

Specify the RCS keystore and truststore. For example:

connectorserver.trustStoreFile=security/truststore.pkcs12
connectorserver.trustStoreType=PKCS12
connectorserver.trustStorePass=changeit
connectorserver.keyStoreFile=security/keyStore.pkcs12
connectorserver.keyStoreType=PKCS12
connectorserver.keyStorePass=changeit
connectorserver.keyPass=changeit

Generate Keys for an RCS in Client Mode

Generate the RCS private/public key pair and create a new PKCS12 keystore:

keytool \
-genkeypair \
-keyalg EC \
-alias icf-rcs \
-dname "CN=icf.example.com,O=Example Corp,C=FR" \
-keystore rcsKeystore \
-storetype PKCS12 \
-storepass changeit \

Verify the contents of the new keystore:

keytool \
-list \
-v \
-keystore rcsKeystore
Enter keystore password:  changeit
Keystore type: PKCS12
Keystore provider: SUN

Your keystore contains 1 entry

Alias name: icf-rcs
Creation date: Jul 13, 2020
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=icf.example.com, O=Example Corp, C=FR
Issuer: CN=icf.example.com, O=Example Corp, C=FR
Serial number: 611e093d
Valid from: Mon Jul 13 23:58:49 SAST 2020 until: Sun Oct 11 23:58:49 SAST 2020
Certificate fingerprints:
SHA1: Fingerprint
SHA256: Fingerprint
Signature algorithm name: SHA256withECDSA
Subject Public Key Algorithm: 256-bit EC key
...

Export the RCS certificate:

keytool \
-export \
-alias icf-rcs \
-file rcs.cert \
-keystore rcsKeystore.pkcs12
Enter keystore password: changeit
Certificate stored in file <rcs.cert>

If you are not using a self-signed certificate, have the certificate signed by a Certificate Authority (CA):

Create a Certificate Signing Request (CSR):

keytool \
-keystore rcsKeystore.pkcs12 \
-certreq \
-alias icf-rcs \
-file rcs.csr

more rcs.csr
-----BEGIN NEW CERTIFICATE REQUEST-----

MIIEKTCCA9QCAQAwVzELMAkGA1UEBhMCRlIxCzAJBgNVBAgTAkZSMQswCQYDVQQH
xZ47rzcY6OrElh8+/TYG50NRqcQYMzm4CefCrhxTm6dHW4XQEa24tHmHdUmEaVys
A1UdDgQWBBSivxV9AzgbrIo3gG6vCBlNaXf3wjANBglghkgBZQMEAwIFAANAADA9
…
AhxL791/ikf1hqxOD3uttV7qumg+TNednsgtk6uOAh0AlINk+1LBeyUkQA7iUHy/
3KLYWog/Npu5USdCeA==

-----END NEW CERTIFICATE REQUEST-----

Submit the CSR to your CA for signature.

Import the signed certificate into the RCS keystore:

keytool \
-importcert \
-trustcacerts \
-file rcs.cert \
-keystore rcsKeystore.pkcs12 \
-storetype pkcs12 \
-alias icf-rcs
Enter keystore password: changeit
Certificate reply was installed in keystore

If your CA certificate is not trusted, you might need to import the CA certificate into the keystore, too.

Import the RCS certificate into the RCS truststore:

keytool \
-import \
-alias icf-rcs \
-keystore /path/to/openidm/truststore \
-file rcs.cert
Enter keystore password: changeit
Owner: CN=icf.example.com, O=Example Corp, C=FR
Issuer: CN=icf.example.com, O=Example Corp, C=FR
Serial number: 611e093d
Valid from: Fri Apr 05 16:04:04 CEST 2019 until: Mon Aug 17 16:04:04 CEST 2020
Certificate fingerprints:
MD5:  Fingerprint
SHA1: Fingerprint
SHA256: Fingerprint
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit DSA key
Version: 1
Trust this certificate? [no]:  yes
Certificate was added to keystore

Export the Identity Cloud self-signed certificate:

keytool \
-export \
-alias openidm-localhost \
-keystore keystore.jceks \
-storetype jceks \
-file idm.cert \
Enter keystore password: changeit
Certificate stored in file <idm.cert>

Import the Identity Cloud self-signed certificate into the RCS truststore:

keytool \
-import \
-alias openidm-localhost \
-keystore /path/to/rcs/security/truststore.pkcs12 \
-storetype pkcs12 \
-file idm.cert
Enter keystore password: changeit

Owner: CN=openidm-localhost, O=OpenIDM Self-Signed Certificate, OU=None, L=None, ST=None, C=None
Issuer: CN=openidm-localhost, O=OpenIDM Self-Signed Certificate, OU=None, L=None, ST=None, C=None
Serial number: 16981c79d8d
Valid from: Wed Feb 13 15:35:36 CET 2019 until: Thu Mar 15 15:35:36 CET 2029
Certificate fingerprints:
MD5:  fingerprint
SHA1: fingerprint
SHA256: fingerprint
Signature algorithm name: SHA512withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3
Trust this certificate? [no]:  yes

Certificate was added to keystore