How To
ForgeRock Identity Cloud

How do I implement a Remote Connector Server (RCS) for Identity Cloud?

Last updated Sep 22, 2021

The purpose of this article is to provide information on implementing an RCS for Identity Cloud and includes troubleshooting steps.


1 reader recommends this article

Introduction

The Java® RCS is required for Identity Cloud to remotely connect to any supported identity resource server via connectors. These connectors run in Identity Cloud. See About Identity Cloud connectors for further information. 

You can run the connector server on the same host as the identity resource server, or you can run it on a different host, for example, that’s dedicated to hosting only connectors.

Preparing to implement the RCS

Before you start implementing the RCS, you should consider the following recommendations:

  • Setting up the RCS, connectors and mappings should be the first thing you do during implementation to ensure you have user data flowing into Identity Cloud.
  • You should implement the RCS in all three Identity Cloud environments (Development, Staging and Production).
  • Always use dedicated RCS instances and external identity servers for each Identity Cloud environment because each environment has different needs. For example, Development will only contain test data whereas Production will hold real data. Separating the RCS and external identity servers for each environment means you will not impact Production data during testing.
  • Physically locate the RCS as close to the external identity servers as possible to reduce latency.
  • Cluster the RCS to achieve high availability. Although this step is considered optional, it is strongly recommended to prevent the RCS from being a single point of failure.

Prerequisites

  • You have three working Identity Cloud environments (Development, Staging, and Production).
  • You have corresponding external identity servers set up for each environment.
  • Java 11 is installed on the server where you want to install the RCS.
  • You have set the JAVA_HOME environment variable to point to your Java 11 install.

Implementing the RCS

Note

The documentation covers the steps needed to implement the RCS: Before you begin. This article references the steps in the documentation, but goes further to include additional checks along the way to help ensure a successful implementation. It also reinforces the need to implement the RCS in all three environments (Development, Staging, and Production).

The steps to implement the RCS are as follows:

  1. Navigate to the Admin UI in your Identity Cloud Development environment.
  2. Register a remote server.
  3. Reset the client secret (unless you have already done this and know the password).
  4. Download a remote server.
  5. Configure a remote server to connect to Identity Cloud.
    • In the Development environment, you should only specify one instance in the connectorserver.url, for example: wss://openam-<YourTenantName>.forgerock.io/openicf/0
    • In the Staging and Production environments, you should specify three instances for the connectorserver.url, for example: wss://openam-<YourTenantName>.forgerock.io/openicf/0 wss://openam-<YourTenantName>.forgerock.io/openicf/1 wss://openam-<YourTenantName>.io/openicf/2
  6. Check that the remote server connection is working before you continue by navigating to Identities > Connect in the Admin UI. It should show as connected.
  7. Install and configure a connector:
    • In the Identity Cloud Admin UI, navigate to Native Consoles > Identity Management > Configure > Connectors to configure your connector.
    • If you want to use a scripted connector or configure a connector that is not supported in the Admin UI, you can configure it via REST: Create a connector configuration over REST.
  8. Check that the connector is successfully connected to the external identity server by navigating to the Data tab in the connector. You should see user data from your external identity server.
  9. Create a mapping between identities in Identity Cloud and identities in your identity server:
  10. Perform an initial reconciliation based on your mapping.
  11. Register a server cluster if you plan to set up load balancing or failover.
  12. Navigate to the Admin UI in your Identity Cloud Staging environment.
  13. Repeat steps 2 to 11 in your Staging environment.
  14. Navigate to the Admin UI in your Identity Cloud Production environment.
  15. Repeat steps 2 to 11 in your Production environment.

After implementation

Once you have successfully implemented the RCS, you should:

Changing the JVM heap size

Changing the JVM heap size can improve performance and reduce the time it takes to run reconciliations. You should try different heap sizes to see what impact it has to determine the best heap size for your setup.

You can set the JVM heap size via the OPENICF_OPTS environment variable. For example, to set the maximum heap size to 1GB, you would enter the following prior to starting the RCS:

On Unix® and Linux® systems:

$ cd /path/to/openicf/bin $ export OPENICF_OPTS="-Xmx1024m" $ ./ConnectorServer.sh /run

On Microsoft® Windows® systems:

C:\> cd \path\to\openicf\bin C:\path\to\openicf\bin> set OPENICF_OPTS=-Xmx1024m  C:\path\to\openicf\bin> ConnectorServer.bat /run

Troubleshooting

First you should establish whether the RCS is connected and if the connector is receiving data:

  • Check if the remote server connection is working by navigating to Identities > Connect in the Admin UI. It should show as connected.
  • Check that the connector is successfully connected to the external identity server by navigating to Native Consoles > Identity Management > Configure > [Connector] > Data. You should see user data from your external identity server if it's receiving data.
Note

If you are seeing unexplained slowness or instability in your Development environment, you should check connectorserver.url is set correctly in your ConnectorServer.properties file. Development environments should only list one URL, for example: wss://openam-<YourTenantName>.forgerock.io/openicf/0

If the RCS is not connected, you should:

  1. Verify the settings in your ConnectorServer.properties file (located in the /path/to/openicf/conf directory) are correct for your environment and update if needed.
  2. Reset the client secret to the known password if there is a chance someone else could have changed it.
  3. Enable debug logging as detailed in How do I enable debug logging and log rotation for the Remote Connector Server (RCS)?
  4. Check the logs (located in the /path/to/openicf/logs directory) for clues to see if you can resolve your issues yourself. Common error messages to look out for are:
Error message Details

 [name of rcs] 0 active WebSocket(s), 3 remaining permits

(repeating)

This error message means the RCS cannot obtain a connection to Identity Cloud. You should check the following settings in the ConnectorServer.properties file and update as needed:

  • connectorserver.url: should be similar to:
    • wss://openam-<YourTenantName>.forgerock.io/openicf/0 in your Development environment.
    • wss://openam-<YourTenantName>.forgerock.io/openicf/0 wss://openam-<YourTenantName>.forgerock.io/openicf/1 wss://openam-<YourTenantName>.io/openicf/2 in your Staging and Production environments.
  • connectorserver.tokenEndpoint: should be similar to: https://openam-<YourTenantName>.forgerock.io/am/oauth2/realms/root/realms/alpha/access_token
  • connectorserver.clientSecret: should contain the correct client secret for the RCSClient in the alpha realm.
StaggeredConnectionCreator: timed out resolving connection promise

This error message means the HTTP connection is being made but upgrading the connection to a WebSocket is failing because the RCS points to an invalid URL. You should check the following setting in the ConnectorServer.properties file and update as needed:

  • connectorserver.url: should be similar to:
    • wss://openam-<YourTenantName>.forgerock.io/openicf/0 in your Development environment.
    • wss://openam-<YourTenantName>.forgerock.io/openicf/0 wss://openam-<YourTenantName>.forgerock.io/openicf/1 wss://openam-<YourTenantName>.io/openicf/2 in your Staging and Production environments.

If the connector is not receiving data, you should verify the connector settings are correct and update them if needed.

If you're still experiencing issues after taking these troubleshooting steps, please raise a ticket with ForgeRock Support.

Raising a ticket

To help us troubleshoot issues with the RCS, please gather the following details and submit them with your support ticket:

  • Collect the logs from the RCS server (located in the /path/to/openicf/logs directory) and indicate what timezone is used for logging.
  • Collect all the idm- prefixed logs from Identity Cloud as explained in View Audit Logs.
  • Collect the ConnectorServer.properties file (located in the /path/to/openicf/conf directory).
  • Confirm the versions of the RCS and connectors you are experiencing issues with.
  • Provide details about the environment where you are running the RCS, including whether they are clustered?
  • Provide details of any configuration changes you made prior to experiencing issues.
  • Provide any scripts you use in your connectors.

See Also

How do I upgrade the Remote Connector Server (RCS) for Identity Cloud and IDM?

How do I run a Remote Connector Server (RCS) as a Service?

RCS in Identity Cloud

Sync Identities

About Identity Cloud connectors


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.