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. -
Install and configure the RCS Agent. The RCS Agent acts as a websocket proxy between Identity Cloud and RCS instances.
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
-
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.
-
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:
-
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
-
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 | ||
---|---|---|---|---|---|
|
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 ( |
rcs1 |
||
|
Client |
URL of the server on which Identity Cloud runs. |
|||
|
Client |
Unique identifier for the RCS. This must be set if you are using the RCS Agent. |
MY_UNIQUE_RCS_HOST_ID |
||
|
Client |
Proxy server host. |
|||
|
Client |
Proxy server port number. |
|||
|
Client |
Proxy server principal. |
|||
|
Client |
Proxy server password. |
|||
|
Client |
WebSocket connections housekeeping interval, in seconds. |
9 |
||
|
Client |
WebSocket groups check interval, in seconds. |
900 |
||
|
Client |
Number of WebSocket connections to open. |
3 |
||
|
Client |
Time to live of a WebSocket connection, in seconds. |
88 |
||
|
Client |
Time (in seconds) before a new connection can be established. |
26 |
||
|
Client |
Token endpoint from which to retrieve the access token, if you are using OAuth2 to authenticate against AM. |
|
||
|
Client |
OAuth2 token scope, if you are using OAuth2 to authenticate against AM. |
fr:idm:* |
||
|
Client |
OAuth2 Client ID for which to request an access token. |
connectorServer |
||
|
|||||
|
Client |
OAuth2 Client Secret. |
openidm |
||
|
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 |
300 |
||
|
Both |
The RCS truststore file. You do not need to set this property if the RCS certificate is a CA-signed certificate. |
|
||
|
Both |
The RCS truststore type. You do not need to set this property if the RCS certificate is a CA-signed certificate. |
|
||
|
Both |
The RCS truststore password. You do not need to set this property if the RCS certificate is a CA-signed certificate. |
changeit |
||
|
Both |
The RCS keystore file. You do not need to set this property if the RCS certificate is a CA-signed certificate. |
|
||
|
Both |
The RCS keystore type. You do not need to set this property if the RCS certificate is a CA-signed certificate. |
|
||
|
Both |
The RCS keystore password. You do not need to set this property if the RCS certificate is a CA-signed certificate. |
changeit |
||
|
Both |
The Identity Cloud certificate password. You do not need to set this property if the RCS certificate is a CA-signed certificate. |
changeit |
||
|
Both |
Directory on the RCS host in which connector library file dependencies are located (relative to |
|
||
|
Both |
Directory on the RCS host in which connector .jar files are located (relative to |
|
||
|
Both |
The RCS logger class. |
|
||
|
Both |
Principal to authenticate to the RCS. This property is not used in Identity Cloud. |
anonymous |
||
|
Both |
Password to authenticate to the RCS. This property is not used in Identity Cloud. |
changeit |
||
|
Server |
Whether the connection between Identity Cloud and the RCS should be over SSL. |
false/true |
||
|
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
|
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 |
DocuSign Connector |
|
Configure a Remote Connector Server (RCS) in client mode
In client mode, RCS initiates the connection with a server (either Identity Cloud, or the RCS Agent). 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 RCS using the RCS Agent
The RCS Agent is a smart websocket proxy that serves as a connection between Identity Cloud and RCS instances. The RCS Agent is an optional component when configuring an RCS installation. It reduces the amount of configuration required, since both Identity Cloud 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 Identity Cloud cluster, since RCS no longer needs to know each of the Identity Cloud instances.

There are some current limitations where the RCS Agent can’t be used:
-
Use of the RCS Agent requires Identity Cloud 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 Identity Cloud 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 Identity Cloud, RCS, and the RCS Agent. The RCS Agent acts as a proxy server, so both Identity Cloud and RCS are configured as clients, connecting to the RCS Agent.
Configure the RCS Agent
-
Configure the RCS Agent
Default.properties
file:agent.port
-
Port number for the RCS Agent. This should match the port specified in the Identity Cloud connector server configuration, and the port included in the RCS
connectorserver.url
property. agent.idm_route
-
The endpoint Identity Cloud will use to attempt to communicate with the RCS Agent. This must match the
websocketPath
in the Identity Cloud 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 Identity Cloud 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 Identity Cloud 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 Identity Cloud 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 RCS to use SSL, see Secure the Connection to the RCS With SSL.
agent.idm_principal
-
The account name Identity Cloud uses to connect to the RCS Agent. This should match
principal
in the Identity Cloud connector server configuration. agent.idm_secret
-
The password Identity Cloud uses to connect to the RCS Agent. This should match
key
in the Identity Cloud 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 asAGENT_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 Identity Cloud to use the RCS Agent
-
Create the connector server core configuration in Identity Cloud:
curl \ --header "Authorization: Bearer *token*" \ --header "Accept-API-Version: resource=1.0" \ --header "Content-Type: application/json" \ --request POST \ --data '{ "type" : "remoteConnectorServer", "systemType" : "provisioner.openicf" }' \ "http://<tenant-env-fqdn>/openidm/system?_action=createConnectorServerCoreConfig"
-
Update the connector server configuration in Identity Cloud with the details to connect to the RCS Agent:
Update the connector server configuration in Identity Cloud
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, "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://<tenant-env-fqdn>/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 } ] }
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 Identity Cloud will try to communicate with, and must match what is set in theagent.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 theagent.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 theagent.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 Identity Cloud, which uniquely identifies each Identity Cloud instance. In most cases, no further action is required, but you may need to adjustagent.max_http_size
oragent.max_frame_bytes
in your RCS Agent settings if, for example, you see amax frame length has been exceeded
message in the RCS Agent log. -
Configure RCS to use the RCS Agent
-
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 Identity Cloud and RCS, this must only have one address, even if you are running Identity Cloud as a cluster. This must be a websocket address (for examplewss://localhost:8787/rcs
), ending with the endpoint specified in theagent.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 ifconnectorserver.hostId
is not set.
-
-
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 theagent.rcs_principal
property in the RCS AgentDefault.properties
file. Configureconnectorserver.password
to match theagent.rcs_secret
property. -
If using OAuth2, configure
connectorserver.tokenEndpoint
,connectorserver.clientId
,connectorserver.clientSecret
, andconnectorserver.scope
to match the settings in the RCS AgentDefault.properties
file foragent.token_introspect_uri
,agent.token_client_id
,agent.token_client_secret
, andagent.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 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 thewss
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