IDM 7.2.1

Remote connectors

In most cases, IDM bundles the connectors required to connect to remote resources, and assumes that the connector will run on the same host as IDM. Sometimes, a connector cannot run on the same host as IDM. This might be for security or network reasons, or because IDM runs in the cloud while the resource is "on-prem". Connectors that do not run on the same host as IDM are called remote connectors. To run remotely, a connector needs a remote connector server (RCS), that runs on the same host as the connector. IDM accesses the connector through the RCS.

Running connectors remotely requires the following high-level steps:

  1. Install an RCS (either .NET or Java) on your on-prem server.

  2. 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 or .dll file on your remote server, in the /path/to/openicf/connectors/ directory.

  3. Configure IDM to connect to the RCS.

  4. Install and configure the RCS Agent. The RCS Agent acts as a websocket proxy between IDM and RCS instances.

For a list of supported RCS versions, and compatibility between versions, see IDM / ICF Compatibility Matrix.

Install a Remote Connector Server (RCS)

There are two types of RCS:

  • Java: Use the Java RCS if your Java connector needs to run in a different JVM to IDM. Unless the remote resource you are connecting to needs the .NET Powershell connector, this is the recommended RCS to use.

    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

    1. Download and extract the Java RCS from the ForgeRock BackStage download site.

    2. Change to the openicf directory:

      cd /path/to/openicf

    3. 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.

      • In server mode, the RCS uses a connectorserver.key property to authenticate the connection. The default value of the key is a hashed value of the string changeit. You cannot set this property directly in the configuration file. To change its value, use the command ConnectorServer.sh /setKey. This example sets the key value to Passw0rd:

        /path/to/openicf/bin/ConnectorServer.sh /setKey Passw0rd
Key has been successfully updated.

        In client mode, this is not necessary, and may be skipped. For more information about the differences between client mode and server mode, see Configure a Remote Connector Server (RCS).

    4. 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

    5. To stop the Java RCS, press CTRL + C, or q in the terminal where you started the server.

    Install a Java RCS on Windows

    1. Download and extract the Java RCS from the ForgeRock BackStage download site.

    2. In a Command Prompt window, change to the openicf directory:

      C:\> cd C:\path\to\openicf

    3. 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.

      • In server mode, the RCS uses a connectorserver.key property to authenticate the connection. The default value of the key is a hashed value of the string changeit. You cannot set this property directly in the configuration file. To change its value, use the ConnectorServer.bat /setKey command. This example sets the key value to Passw0rd:

        c:\path\to\openicf> bin\ConnectorServer.bat /setKey Passw0rd
Key has been successfully updated.

        In client mode, this is not necessary, and may be skipped. For more information about the differences between client mode and server mode, see Configure a Remote Connector Server (RCS).

    4. 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

    5. The RCS is now running, and listening on port 8759, by default.

      Log files are available in the \path\to\openicf\logs directory.

    6. To stop the Java RCS, press ^ + C.

  • .NET: Use the .NET RCS if you are using the PowerShell connector to connect to an identity store. IDM communicates with the .NET RCS over the network, and the RCS runs the Powershell connector.

    Set Up a .NET RCS
    Set Up a .NET RCS

    The .NET RCS is distributed in two file formats:

    • openicf-version-dotnet.msi is a wizard that installs the RCS as a Windows service.

    • openicf-version-dotnet.zip is just a bundle of files required to run the RCS.

      1. Depending on how you want to install the RCS, download the corresponding file from the ForgeRock BackStage download site.

      2. Follow one of these procedures to install the RCS:

        Install the RCS as a Service

        1. Double-click the openicf-version-dotnet.msi installation file and complete the wizard.

          You must run the wizard as a user who has permission to start and stop a Windows service; otherwise, the service will not start.

          Select Typical as the Setup Type.

          When the wizard has completed, the RCS is installed as a Windows service.

        2. Open the Microsoft Services Console and make sure that the RCS is listed there.

          The name of the service is OpenICF Connector Server, by default.

          dotnet-service

        3. Make sure that the RCS is not currently running. If it is running, use the Microsoft Services Console to stop it.

        Unpack the RCS Zip

        1. If you do not want to run the RCS as a Windows service, download and extract the openicf-version-dotnet.zip file.

        2. If you have already extracted the .zip file and then decide to run the RCS as a service, install the service manually with the following command:

          .\ConnectorServerService.exe /install /serviceName service-name

      3. At the command prompt, change to the directory where the RCS was installed, for example:

        cd "c:\Program Files (x86)\ForgeRock\OpenICF"

      4. By default, the RCS outputs log messages to a file named connectorserver.log , in the \path\to\openicf directory. To change the location of the log file, set the initializeData parameter in the configuration file. The following example sets the log directory to C:\openicf\logs\connectorserver.log:

        <add name="file" type="System.Diagnostics.TextWriterTraceListener" initializeData="C:\openicf\logs\connectorserver.log" traceOutputOptions="DateTime">
    <filter type="System.Diagnostics.EventTypeFilter" initializeData="Information"/>
</add>

      5. Run the ConnectorServerService /setKey command to set a secret key for the RCS. The key can be any string value. This example sets the secret key to Passw0rd:

        ConnectorServerService /setKey Passw0rd
Key has been successfully updated.

        This key is used by clients connecting to the RCS. The key that you set here must also be set in the IDM RCS configuration.

      6. Edit the RCS configuration.

        The RCS configuration is saved in a file named ConnectorServerService.exe.Config (in the directory where the RCS is installed).

        Check and edit this file, as necessary, to reflect your installation. Specifically, verify that the baseAddress reflects the host and port on which the RCS is installed:

        <system.serviceModel>
  <services>
    <service name="Org.ForgeRock.OpenICF.Framework.Service.WcfServiceLibrary.WcfWebsocket">
      <host>
        <baseAddresses>
          <add baseAddress="http://0.0.0.0:8759/openicf" />
        </baseAddresses>
      </host>
    </service>
  </services>
</system.serviceModel>
        The baseAddress specifies the host and port on which the RCS listens, and is set to http://0.0.0.0:8759/openicf by default. If you set a host value other than the default 0.0.0.0, connections from all IP addresses other than the one specified are denied.
        If Windows Firewall is enabled, you must create an inbound port rule to open the TCP port for the RCS (8759 by default). If you do not open the TCP port, IDM won’t be able to contact the RCS. For more information, see the corresponding Microsoft documentation.

      7. Configure the RCS to use SSL:

        • Open a Powershell terminal as a user with administrator privileges, then change to the ICF installation directory:

          cd 'C:\Program Files (x86)\ForgeRock\OpenICF'

        • Use an existing CA certificate, or use the New-SelfSignedCertificate cmdlet to create a self-signed certificate:

          New-SelfSignedCertificate -DnsName "dotnet", "dotnet.example.com" -CertStoreLocation "cert:\LocalMachine\My"
PSParentPath: Microsoft.PowerShell.Security\Certificate::LocalMachine\My

Thumbprint                                Subject
----------                                -------
770F531F14AF435E963E14AD82B70A47A4BFFBF2  CN=dotnet

        • Assign the certificate to the RCS:

          .\ConnectorServerService.exe /setCertificate
Select certificate you want to use:
Index  Issued To                Thumbprint
-----  ---------                -------------------------

0)  dotnet                    770F531F14AF435E963E14AD82B70A47A4BFFBF2 0
Certificate Thumbprint has been successfully updated to 770F531F14AF435E963E14AD82B70A47A4BFFBF2.

        • Bind the certificate to the RCS port (8759 by default). To bind the certificate:

        • Use the New-Guid cmdlet to generate a new UUID:

          New-Guid
Guid
----
0352cf0f-2e7a-4aee-801d-7f27f8344c77

          • Enter the netsh http console and add the certificate thumbprint generated in the previous step, and the UUID that you have just generated:

            netsh
netsh> http
netsh http> add sslcert ipport=0.0.0.0:8759 certhash=770F5…​FFBF2 appid={0352c…​4c77}
SSL Certificate successfully added

        • Change the RCS configuration (in the ConnectorServerService.exe.Config file) to use HTTPS and not HTTP.

          Change baseAddress="http…​" to baseAddress="https…​":

          <host>
  <baseAddresses>
    ...
    <add baseAddress="https://0.0.0.0:8759/openicf"/>
  </baseAddresses>
</host>

          Change httpTransport to httpsTransport:

          <httpsTransport authenticationScheme="Basic" realm="OpenICF">
    <webSocketSettings transportUsage="Always" createNotificationOnConnection="true" .../>
</httpsTransport>

        • Export the certificate:

          • Launch the certificate management MMC (certlm.msc).

          • Right-click the dotnet certificate, and select All Tasks > Export to launch the Certificate Export Wizard.

          • Select Next > No, do not export the private key > DER encoded binary X.509 (.CER) > Next.

          • Save the file in an accessible location (for example, C:\Users\Administrator\Desktop\dotnet.cer), and click Finish.

        • Import the certificate into the IDM truststore:

          • Transfer the certificate from the Windows machine to the machine that’s running IDM.

          • Change to the openidm/security directory and use the Java keytool command to import the certificate:

            cd /path/to/openidm/security
keytool -import -alias dotnet -file ~/Downloads/dotnet.cer -keystore ./truststore
Enter keystore password: changeit
Owner: CN=dotnet
Issuer: CN=dotnet
Serial number: 1e3af7baed05ce834da5cd1bf1241835
Valid from: Tue Aug 08 15:58:32 SAST 2017 until: Wed Aug 08 16:18:32 SAST 2018
Certificate fingerprints:
MD5:  D1:B7:B7:46:C2:59:1A:3C:94:AA:65:99:B4:43:3B:E8
SHA1: 77:0F:53:1F:14:AF:43:5E:96:3E:14:AD:82:B7:0A:47:A4:BF:FB:F2
SHA256: C0:52:E2:E5:E5:72:9D:69:F8:11:4C:B8:4C:E4:E3:1C:19:95:86:19:70:E5:31:FA:D8:81:4B:F2:AC:30:9C:73
Signature algorithm name: SHA256withRSA
Version: 3

…​

Trust this certificate? [no]: yes
Certificate was added to keystore

        • When you configure the RCS, remember to set "useSSL": true.

      8. Check the trace settings under system.diagnostics in the RCS configuration file:

        <system.diagnostics>
  <trace autoflush="true" indentsize="4">
    <listeners>
      <remove name="Default" />
      <add name="console" />
      <add name="file" />
    </listeners>
  </trace>
  <sources>
    <source name="ConnectorServer" switchName="switch1">
      <listeners>
        <remove name="Default" />
        <add name="file" />
      </listeners>
    </source>
  </sources>
  <switches>
    <add name="switch1" value="Information" />
  </switches>
  <sharedListeners>
    <add name="console" type="System.Diagnostics.ConsoleTraceListener" />
    <add name="file" type="System.Diagnostics.TextWriterTraceListener"
         initializeData="logs\ConnectorServerService.log"
         traceOutputOptions="DateTime">
      <filter type="System.Diagnostics.EventTypeFilter" initializeData="Information" />
    </add>
  </sharedListeners>
</system.diagnostics>

        The RCS uses the standard .NET trace mechanism. For more information about tracing options, see Microsoft’s .NET documentation for System.Diagnostics.

        The default trace settings are a good starting point. For less tracing, set the EventTypeFilter’s initializeData to Warning or Error. For very verbose logging, set the value to Verbose or All. The logging level has a direct effect on the RCS performance, so take care when setting this level.

      9. Start the .NET RCS in one of the following ways:

        1. Start the server as a Windows service, by using the Microsoft Services Console.

          Locate the RCS service (OpenICF connector server), and click Start the service or Restart the service.

          The service runs with the credentials of the "run as" user (System, by default).

        2. Start the server as a Windows service, by using the command line.

          In the Windows Command Prompt, run the following command:

          net start ConnectorServerService

          To stop the service, run the following command:

          net stop ConnectorServerService

        3. Start the server without using Windows services.

          In the Windows Command Prompt, change to the RCS installation directory. The default location is c:\> cd "c:\Program Files (x86)\ForgeRock\OpenICF".

          Start the server with the following command:

          ConnectorServerService.exe /run
          This command starts the RCS with the credentials of the current user. It does not start the server as a Windows service.

Both RCS types 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 IDM server.

rcs1

url

Client

URL of the server on which IDM 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. This must be set if you are using the RCS Agent.

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.

9

groupCheckInterval

Client

WebSocket groups check interval, in seconds.

900

webSocketConnections

Client

Number of WebSocket connections to open.

3

connectionTtl

Client

Time to live of a WebSocket connection, in seconds.

88

newConnectionsInterval

Client

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

26

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 IDM 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 IDM truststore file. You do not need to set this property if the IDM certificate is a CA-signed certificate.

security/truststore.pkcs12

trustStoreType

Both

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

PKCS12

trustStorePass

Both

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

changeit

keyStoreFile

Both

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

security/keyStore.pkcs12

keyStoreType

Both

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

PKCS12

keyStorePass

Both

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

changeit

keyPass

Both

The IDM certificate password. You do not need to set this property if the IDM 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 if the RCS obtains its access token through ForgeRock® Access Management (AM) (which is the case when IDM is running in ForgeRock Identity Cloud).

anonymous

password

Both

Password to authenticate to the RCS. This property is not used if the RCS obtains its access token through AM (which is the case when IDM is running in ForgeRock Identity Cloud).

changeit

useSSL

Server

Whether the connection between IDM and the RCS should be over SSL.

false/true

port

Server

Port on which the RCS listens for the connection from IDM.

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
Sample connectorserver.properties file for server mode 
connectorserver.port=8759
connectorserver.pingPongInterval=60
connectorserver.principal=anonymous
connectorserver.password=changeit
connectorserver.useSSL=true
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.bundleDir=connectors
connectorserver.libDir=lib
connectorserver.key=lmA6bMfENJGlIDbfrVtklXFK32s\=
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

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

  • psft.jar

  • psjoa.jar

Configure a Remote Connector Server (RCS)

RCS runs in one of two modes:

Client mode

In client mode, RCS initiates the connection with a server (either IDM, or the RCS Agent). Run the RCS in client mode if your data store is protected by a firewall or DMZ, or if you intend to use the RCS Agent.

The following diagram shows an RCS in client mode:

connector-server-client
Server mode

In server mode, RCS acts as the server, with IDM acting as a client. IDM initiates the connection to the RCS. Run the RCS in server mode if IDM can initiate the connection and has access through any firewalls.

The following diagram shows an RCS in server mode:

connector-server-server

This example shows how to retrieve the RCS types over REST:

List the RCS Types 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system?_action=availableConnectorServers"
{
  "connectorServers": [
    {
      "displayName": "Remote Connector Server",
      "systemType": "provisioner.openicf",
      "type": "remoteConnectorServer"
    },
    {
      "displayName": "Remote Connector Servers Group",
      "systemType": "provisioner.openicf",
      "type": "remoteConnectorServersGroup"
    },
    {
      "displayName": "Remote Connector Server in Client mode",
      "systemType": "provisioner.openicf",
      "type": "remoteConnectorClient"
    },
    {
      "displayName": "Remote Connector Servers Group in Client mode",
      "systemType": "provisioner.openicf",
      "type": "remoteConnectorClientsGroup"
    }
  ]
}

Configure RCS in Client Mode

The RCS configuration will differ between server mode and client mode. See RCS Properties for a list of properties and the mode to which they apply.

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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "type": "remoteConnectorClient",
  "systemType": "provisioner.openicf"
}' \
"http://localhost:8080/openidm/system?_action=createConnectorServerCoreConfig"
{
  "displayName": "",
  "name": "",
  "enabled": true,
  "useSSL": false
}

IDM 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 IDM. 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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorClients": [
    {
      "displayName": "On premise 1",
      "name": "onprem",
      "enabled": true
    }
  ]
}' \
"http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"
{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorClients": [
    {
      "displayName": "On premise 1",
      "name": "onprem",
      "enabled": true
    }
  ]
}

Configure RCS in Server Mode

The RCS configuration will differ between server mode and client mode. See RCS Properties for a list of properties and the mode to which they apply.

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

Create a Core RCS Configuration (Server Mode) 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "type": "remoteConnectorServer",
  "systemType": "provisioner.openicf"
}' \
"http://localhost:8080/openidm/system?_action=createConnectorServerCoreConfig"
{
  "displayName": "",
  "proxyPassword": null,
  "proxyHost": null,
  "enabled": true,
  "useSSL": false,
  "proxyPort": 8080,
  "port": "",
  "name": "",
  "host": "",
  "proxyUser": null,
  "housekeepingInterval": 600,
  "connectionGroupCheckInterval": 900,
  "pingPongInterval": 300,
  "key": "password",
  "webSocketConnections": 2
}

IDM returns the required configuration properties for an RCS in server mode. The configuration that is returned is not functional. It does not contain the specific property values, such as the host name and port of the RCS.

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

Create a New RCS Configuration (Server Mode) 
curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorServers": [
    {
      "type": "remoteConnectorServer",
      "displayName": "Remote Connector Server 1",
      "proxyPassword": null,
      "proxyHost": null,
      "enabled": true,
      "useSSL": false,
      "proxyPort": 8080,
      "port": 8759,
      "name": "rcs1",
      "host": "rcs.example.com",
      "proxyUser": null,
      "housekeepingInterval": 600,
      "connectionGroupCheckInterval": 900,
      "pingPongInterval": 300,
      "key": "Passw0rd",
      "webSocketConnections": 2
    }
  ]
}' \
"http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"
{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorServers": [
    {
      "type": "remoteConnectorServer",
      "displayName": "Remote Connector Server 1",
      "proxyPassword": null,
      "proxyHost": null,
      "enabled": true,
      "useSSL": false,
      "proxyPort": 8080,
      "port": 8759,
      "name": "rcs1",
      "host": "rcs.example.com",
      "proxyUser": null,
      "housekeepingInterval": 600,
      "connectionGroupCheckInterval": 900,
      "pingPongInterval": 300,
      "key": {
        "$crypto": {
          "type": "x-simple-encryption",
          "value": {
            "cipher": "AES/CBC/PKCS5Padding",
            "stableId": "openidm-sym-default",
            "salt": "3Mq1UJuZXqANx2AzUtbFbg==",
            "data": "4WHBEI3nSVWJ2DfIs2dPZg==",
            "keySize": 16,
            "purpose": "idm.config.encryption",
            "iv": "BvFAQ4sjwJCNY2e7WZPkGw==",
            "mac": "ximBz/BlqC8SEsBTuYQX5Q=="
          }
        }
      },
      "webSocketConnections": 2
    }
  ]
}

Configure RCS using the RCS Agent

The RCS Agent is a smart websocket proxy that serves as a connection between IDM and RCS instances. The RCS Agent is an optional component when configuring an RCS installation. It reduces the amount of configuration required, since both IDM and RCS only need to know the address of the RCS Agent (a single point of ingress). This also means it is easier to scale an IDM cluster, since RCS no longer needs to know each of the IDM instances.

connector-rcs-agent

There are some current limitations where the RCS Agent can’t be used:

  • Use of the RCS Agent requires IDM version 7.1 or newer, and RCS version 1.5.20.0 or newer. If you are attempting to connect to an older version of either of these products, the RCS Agent is not available.

  • The .NET version of RCS does not currently support the RCS Agent.

Install the RCS Agent

The RCS Agent is a separate application from IDM and RCS. You can download it from the ForgeRock BackStage download site.

Using Docker to deploy and manage the RCS Agent is recommended, and a Dockerfile to create a Docker image is included in the downloaded .zip file. To build the Docker image, in the RCS install directory run:

docker build . -t rcs-agent:latest

Once the Docker image has been built, start the RCS Agent:

docker run -t -i -p 8787:8787 -m 512M \
-e ARGS="-p /Default.properties" \
-e LOGGING_PROPERTIES="/logging.properties" \
-v ${PWD}/Default.properties:/Default.properties \
-v ${PWD}/logging.properties:/logging.properties \
rcs-agent:latest

You can also use the RCS Agent without Docker, by running the .jar file directly:

java \
-server \
-XX:MaxRAMPercentage=80 \
-XX:InitialRAMPercentage=80 \
-XX:MaxTenuringThreshold=1 \
-Djava.util.logging.config.file=logging.properties \
-XshowSettings:vm \
-jar connector-framework-agent.jar \
org.forgerock.openicf.framework.agent.AgentServer -p Default.properties
VM settings:
Max. Heap Size (Estimated): 12.80G
Using VM: OpenJDK 64-Bit Server VM

Mar 17, 2021 5:17:20 PM org.forgerock.openicf.framework.agent.AgentServer start
INFO: Agent starting :8787

Configure the RCS Agent

Using the RCS Agent requires configuration in IDM, RCS, and the RCS Agent. The RCS Agent acts as a proxy server, so both IDM and RCS are configured as clients, connecting to the RCS Agent.

Configure the RCS Agent

  1. Configure the RCS Agent Default.properties file:

    agent.port

    Port number for the RCS Agent. This should match the port specified in the IDM connector server configuration, and the port included in the RCS connectorserver.url property.

    agent.idm_route

    The endpoint IDM will use to attempt to communicate with the RCS Agent. This must match the websocketPath in the IDM connector server configuration.

    agent.rcs_route

    The endpoint RCS will use to attempt to communicate with the RCS Agent. This must match the endpoint included in connectorserver.url in the RCS properties.

    agent.health_route

    The RCS Agent endpoint used to report system health. For example, in a Kubernetes deployment, this route can be polled by Kubernetes to monitor the status of the RCS Agent.

    agent.max_http_size

    The maximum size (in bytes) of an HTTP request the RCS Agent will accept. This refers to the initiating requests for IDM and RCS: once a connection is established, a websocket connection is used instead of HTTP.

    agent.max_frame_bytes

    The maximum size (in bytes) of a websocket frame the RCS Agent will accept.

    agent.handshake_timeout_millis

    How long the RCS Agent should wait to complete an initiating handshake with an IDM or RCS instance before timing out.

    agent.shutdown_timeout_millis

    The maximum amount of time for the RCS Agent to perform a graceful shutdown. A graceful shutdown helps IDM instances recover more smoothly during an active recon or sync. If the RCS Agent still hasn’t shut down by the end of the timeout, it will force a shutdown.

    agent.ssl_enabled

    Boolean property enabling or disabling SSL on the RCS Agent. If the RCS Agent is in a protected network behind a reverse proxy or load balancer, it may not be necessary to have this enabled (such as in some cloud environments). If the RCS Agent is exposed directly, or passed through in such a way that the SSL connection is expected to terminate at the Agent, this should be enabled.

    For more information about configuring IDM to use SSL, see Use TLS/SSL. For more information about configuring RCS to use SSL, see Secure the Connection to the RCS With SSL.

    agent.idm_principal

    The account name IDM uses to connect to the RCS Agent. This should match principal in the IDM connector server configuration.

    agent.idm_secret

    The password IDM uses to connect to the RCS Agent. This should match key in the IDM connector server configuration.

    agent.rcs_principal

    The account name RCS uses to connect to the RCS Agent. This should match connectorserver.principal in the RCS properties file. Only used when using basic authentication.

    agent.rcs_secret

    The password RCS uses to connect to the RCS Agent. This should match connectorserver.password in the RCS properties file. Only used when using basic authentication.

    agent.token_introspect_uri

    This is the address the RCS Agent uses to validate the access token provided by an RCS instance. Part of OAuth2 authentication. If you plan to use basic authentication instead of OAuth2, do not configure this property, as OAuth2 settings will take precedence.

    agent.token_client_id

    This is the client ID the RCS Agent uses to validate the access token provided by an RCS instance. Part of OAuth2 authentication. If you plan to use basic authentication instead of OAuth2, do not configure this property, as OAuth2 settings will take precedence.

    agent.token_client_secret

    This is the client secret the RCS Agent uses to validate the access token provided by an RCS instance. Part of OAuth2 authentication. If you plan to use basic authentication instead of OAuth2, do not configure this property, as OAuth2 settings will take precedence.

    agent.required_scopes

    These are the scopes RCS needs to include in its access token to authenticate with the RCS Agent. If multiple scopes are needed, separate each scope with a space. Part of OAuth2 authentication. If you plan to use basic authentication instead of OAuth2, do not configure this property, as OAuth2 settings will take precedence.

    agent.truststore_file

    This is the local path to the truststore file the RCS Agent uses. This is necessary if you are connecting to AM for validating access tokens, and AM is using a self-signed certificate for HTTPS connections. Part of SSL configuration. If AM’s SSL certificate is signed by certificate authorities the Java JDK already trusts, then this does not need to be configured.

    agent.truststore_secret

    Part of SSL configuration. This is the secret key the RCS Agent uses to access the truststore file. If you are using OAuth2, the truststore file must be updated to trust the certificate for the server in agent.token_introspect_uri. Part of SSL configuration. If AM’s SSL certificate is signed by certificate authorities the Java JDK already trusts, then this does not need to be configured.

    agent.keystore_file

    This is the local path to the keystore file the RCS Agent uses. Part of SSL configuration.

    agent.keystore_secret

    This is the secret key the RCS Agent uses to access the keystore file. Part of SSL configuration.

    To better support containerized deployments, any of the agent properties can be specified using environment variables, which will override properties from the config file. Environment variables must be in upper case and use underscores instead of periods. For example, agent.idm_route would be specified as AGENT_IDM_ROUTE.
Sample Default.properties file for the RCS Agent 
# NOTE: these are default config properties when no configuration file provided via -p or --properties
agent.port=8787
agent.idm_route=/openicf
agent.rcs_route=/rcs
agent.health_route=/health
agent.max_http_size=65536
agent.max_frame_bytes=20971520
agent.handshake_timeout_millis=10000
agent.shutdown_timeout_millis=25000
agent.ssl_enabled=false

# IDM Basic Auth
agent.idm_principal=idmPrincipal
agent.idm_secret=idmSecret

# RCS Basic Auth
agent.rcs_principal=rcsPrincipal
agent.rcs_secret=rcsSecret

# RCS OAuth 2.0 Bearer Token Auth with AM integration
#agent.token_introspect_uri=http://am:80/am/oauth2/introspect
#agent.token_client_id=rcsAgentClientId
#agent.token_client_secret=rcsAgentClientSecret
#agent.required_scopes=fr:idm:*

# configure truststore to trust self-signed SSL certificate from agent.token_introspect_uri
#agent.truststore_file=/mounted/path/to/truststore/file
#agent.truststore_secret=truststoreSecret

# configure keystore when agent.ssl_enabled=true
#agent.keystore_file=/mounted/path/to/keystore/file
#agent.keystore_secret=keystoreSecret

Configure IDM to use the RCS Agent

  1. Create the connector server core configuration in IDM:

    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "type" : "remoteConnectorServer",
  "systemType" : "provisioner.openicf"
}' \
"http://localhost:8080/openidm/system?_action=createConnectorServerCoreConfig"

  2. Update the connector server configuration in IDM with the details to connect to the RCS Agent:

    Update the connector server configuration in IDM 
    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorServers": [
    {
      "type": "remoteConnectorServer",
      "displayName": "RCS Agent",
      "enabled": true,
      "useSSL": false,
      "proxyPort": 8080,
      "name": "rcsagent",
      "proxyUser": null,
      "housekeepingInterval": 600,
      "connectionGroupCheckInterval": 900,
      "pingPongInterval": 300,
      "webSocketConnections": 2,
      "host": "localhost",
      "port": 8787,
      "connectionTtl": 3000,
      "websocketPath": "openicf",
      "principal": "idmPrincipal",
      "key": "idmSecret",
      "useAgent": true
    }
  ]
}' \
"http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"
{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorServers": [
    {
      "type": "remoteConnectorServer",
      "displayName": "RCS Agent",
      "enabled": true,
      "useSSL": false,
      "proxyPort": 8080,
      "name": "rcsagent",
      "proxyUser": null,
      "housekeepingInterval": 600,
      "connectionGroupCheckInterval": 900,
      "pingPongInterval": 300,
      "webSocketConnections": 2,
      "host": "localhost",
      "port": 8787,
      "websocketPath": "openicf",
      "principal": "idmPrincipal",
      "key": {
        "$crypto": {
          "type": "x-simple-encryption",
          "value": {
            "cipher": "AES/CBC/PKCS5Padding",
            "stableId": "openidm-sym-default",
            "salt": "c/ydm/RduxT/B8cFLOmLtA==",
            "data": "wk0zEQV5CDCigkevnLBJpQ==",
            "keySize": 16,
            "purpose": "idm.config.encryption",
            "iv": "Kk3lQerGaFLSbNPXeGaO2g==",
            "mac": "cy9QOZTSw2Brf8wGaz/+zg=="
          }
        }
      },
      "useAgent": true
    }
  ]
}

    Alternatively, you can create or edit the provisioner.openicf.connectorinfoprovider.json file in your IDM conf/ directory, applying the same changes.

    Most configuration remains the same as before, but some properties have specific requirements for use with the RCS Agent:

    • websocketPath: This is the endpoint in the RCS Agent that IDM will try to communicate with, and must match what is set in the agent.idm_route property in the RCS Agent configuration.

    • principal: This is the basic authentication username used to connect to the RCS Agent. It must match what is set in the agent.idm_principal property in the RCS Agent configuration.

    • key: This is the basic authentication password, used to connect to the RCS Agent. It must match what is set in the agent.idm_secret property in the RCS Agent configuration.

    • useAgent: This is a boolean property to enable use of the RCS Agent as part of the remote connector process.

      useAgent must be enabled if you intend to use the RCS Agent.
    When using the RCS Agent, an additional header, X-ICF-HostId is sent by IDM, which uniquely identifies each IDM instance. In most cases, no further action is required, but you may need to adjust agent.max_http_size or agent.max_frame_bytes in your RCS Agent settings if, for example, you see a max frame length has been exceeded message in the RCS Agent log.

Configure RCS to use the RCS Agent

  1. In the RCS ConnectorServer.properties file, configure the following properties:

    • connectorserver.url: This is the address for the RCS Agent. Since the RCS Agent is acting as the server for both IDM and RCS, this must only have one address, even if you are running IDM as a cluster. This must be a websocket address (for example wss://localhost:8787/rcs), ending with the endpoint specified in the agent.rcs_route property in the RCS Agent configuration.

    • connectorserver.hostId: This is the unique identifier for your RCS instance.

      connectorserver.hostId must be set if you are using the RCS Agent. The connection will be rejected if connectorserver.hostId is not set.

  2. In the RCS ConnectorServer.properties file, configure authentication using either basic auth, or OAuth2 if you are using AM for authentication (such as in the ForgeRock Identity Platform or ForgeRock Identity Cloud).

    • If using basic authentication, configure connectorserver.principal to match the settings in the agent.rcs_principal property in the RCS Agent Default.properties file. Configure connectorserver.password to match the agent.rcs_secret property.

    • If using OAuth2, configure connectorserver.tokenEndpoint, connectorserver.clientId, connectorserver.clientSecret, and connectorserver.scope to match the settings in the RCS Agent Default.properties file for agent.token_introspect_uri, agent.token_client_id, agent.token_client_secret, and agent.required_scopes (respectively).

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 IDM 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 Server Mode

This example configures a remoteConnectorServersGroup 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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "type" : "remoteConnectorServersGroup",
  "systemType" : "provisioner.openicf"
}' \
"http://localhost:8080/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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorServers": [
    {
      "type": "remoteConnectorServersGroup",
      "displayName": ".NET Failover Group",
      "name" : "dotnet-ha",
      "algorithm" : "failover",
      "serversList" : [
        {"name": "remote-host-1"},
        {"name": "remote-host-2"}
      ]
    }
  ]
}' \
"http://localhost:8080/openidm/config/provisioner.openicf.connectorinfoprovider"
{
  "_id": "provisioner.openicf.connectorinfoprovider",
  "connectorsLocation": "connectors",
  "enabled": true,
  "remoteConnectorServers": [
    {
      "type": "remoteConnectorServersGroup",
      "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. For example, the following excerpt of a PowerShell connector configuration file references the dotnet-ha RCS group created in the previous example:

{
   "connectorRef" : {
     "bundleName" : "MsPowerShell.Connector",
     "connectorName" : "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector",
     "connectorHostRef" : "dotnet-ha",
     "bundleVersion" : "[1.4.3.0,1.5.0.0)"
   },
   ...
 }
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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "type" : "remoteConnectorClientsGroup",
  "systemType" : "provisioner.openicf"
}' \
"http://localhost:8080/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 "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request PUT \
--data '{
  "_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://localhost:8080/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. For example, the following excerpt of a PowerShell connector configuration file references the dotnet-ha RCS group created in the previous example:

{
   "connectorRef" : {
     "bundleName" : "MsPowerShell.Connector",
     "connectorName" : "Org.ForgeRock.OpenICF.Connectors.MsPowerShell.MsPowerShellConnector",
     "connectorHostRef" : "dotnet-ha",
     "bundleVersion" : "[1.4.3.0,1.5.0.0)"
   },
   ...
 }

Secure the Connection to the RCS With SSL

The SSL configuration for an RCS depends on whether you are running the RCS in server mode or in client mode:

  • In server mode, IDM initiates the connection to the RCS.

    The RCS needs a public/private key pair and a certificate (either self-signed or CA-signed). The RCS sends its certificate to the client (IDM) during the SSL handshake.

    If you are using a CA-signed certificate, IDM will trace the certificate back to the root certificate. If you are using a self-signed certificate (or a certificate that depends on an unreachable issuer in the chain from the root certificate), you must import the certificate into the IDM truststore.

  • In client mode, the RCS initiates the connection to IDM. IDM sends its certificate during the SSL handshake. If you are using the IDM 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. IDM 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 IDM and the RCS:

RCS in server mode

  • Set connectorserver.useSSL=true.

  • 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
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
Configure IDM For SSL

In your conf/provisioner.openicf.connectorinfoprovider.json file, set "useSSL" : true.

Generate Keys for an RCS in Server Mode

  1. 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 \

  2. 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
...

  3. 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>

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

    1. 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-----

    2. Submit the CSR to your CA for signature.

  5. 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.

  6. Import the RCS certificate into the IDM 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
Generate Keys for an RCS in Client Mode

  1. 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 \

  2. 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
...

  3. 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>

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

    1. 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-----

    2. Submit the CSR to your CA for signature.

  5. 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.

  6. Import the RCS certificate into the IDM 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

  7. Export the IDM 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>

  8. Import the IDM 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

Example: Use the CSV Connector to Reconcile Users in a Remote CSV Data Store

This example shows reconciliation of users stored in a CSV file on a remote machine. The remote Java RCS lets IDM synchronize its repository with the remote CSV file.

The example assumes that a remote Java RCS is installed and running on a host named remote-host.

The example uses the small CSV data set provided with the Getting Started sample (hr.csv). The CSV connector runs as a remote connector, on the host where the Java RCS is running. Before you start, copy the CSV data file from the Getting Started sample (/path/to/openidm/samples/getting-started/data/hr.csv) to an accessible location on the machine that hosts the remote Java RCS. For example:

cd /path/to/openidm/samples/getting-started/data/
scp hr.csv testuser@remote-host:/home/testuser/csv-sample/data/
Password:**
hr.csv     100%  651     0.6KB/s   00:00

Configure IDM for the Remote CSV Connector Example

  1. Copy the following files to your /path/to/openidm/conf directory:

    sync.json

    A customized mapping file for this example.

    /openidm/samples/example-configurations/provisioners/provisioner.openicf.connectorinfoprovider.json

    A sample RCS configuration.

    /openidm/samples/example-configurations/provisioners/provisioner.openicf-csvfile.json

    A sample connector configuration file.

  2. Edit the RCS configuration file (provisioner.openicf.connectorinfoprovider.json) to match your network setup.

    The following example indicates that the Java RCS is running on the host remote-host, listening on the default port, and configured with a secret key of Passw0rd:

    {
    "remoteConnectorServers" : [
        {
            "name" : "csv",
            "host" : "remote-host",
            "port" : 8759,
            "useSSL" : false,
            "key" : "Passw0rd"
        }
    ]
}

    The name that you set in this file will be referenced in the connectorHostRef property of the connector configuration, in the next step.

    The key that you specify here must match the password that you set when you installed the Java RCS.

  3. Edit the CSV connector configuration file (provisioner.openicf-csvfile.json ) as follows:

    {
    "connectorRef" : {
        "connectorHostRef" : "csv",
        "bundleName" : "org.forgerock.openicf.connectors.csvfile-connector",
        "bundleVersion" : "[1.5.19.0,1.6.0.0)",
        "connectorName" : "org.forgerock.openicf.csvfile.CSVFileConnector"
    },
    ...
    "configurationProperties" : {
        "csvFile" : "/home/testuser/csv-sample/data/hr.csv"
    }
}

    • The connectorHostRef property sets the RCS to use, and refers to the name property you specified in the provisioner.openicf.connectorinfoprovider.json file.

    • The bundleVersion : "[1.5.1.4,1.6.0.0)", must either be exactly the same as the version of the CSV connector that you are using or, if you specify a range, the CSV connector version must be included in this range.

    • The csvFile property must specify the absolute path to the CSV data file that you copied to the remote host on which the Java RCS is running.

  4. Start IDM:

    /path/to/openidm/startup.sh

  5. Verify that IDM can reach the RCS, and that the CSV connector has been configured correctly:

    curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system?_action=test"
[
  {
    "name": "csv",
    "enabled": true,
    "config": "config/provisioner.openicf/csv",
    "objectTypes": [
      "__ALL__",
      "account"
    ],
    "connectorRef": {
      "bundleName": "org.forgerock.openicf.connectors.csvfile-connector",
      "connectorName": "org.forgerock.openicf.csvfile.CSVFileConnector",
      "bundleVersion": "[1.5.0.0,1.6.0.0)"
    },
    "displayName": "CSV File Connector",
    "ok": true
  }
]

    The connector must return "ok": true.

    Alternatively, use the admin UI to verify that IDM can reach the RCS and that the CSV connector is active. Log in to the admin UI (https://localhost:8443/openidm/admin), and select Configure > Connectors. The CSV connector should be listed on the Connectors page, and its status should be Active.

    remote-csv
    Figure 1. Connectors Tab Showing an Active CSV Connector

  6. To test that the connector has been configured correctly, run a reconciliation operation as follows:

    1. Select Configure > Mappings, and click the systemCsvAccounts_managedUser mapping.

    2. Click Reconcile.

      If the reconciliation is successful, the three users from the remote CSV file should have been added to the managed user repository.

      To check this, click Manage > User.

Copyright © 2010-2022 ForgeRock, all rights reserved.