Sync Identities


Register a remote server with your tenant when you want to sync identities, or set up load balancing and failover.

This page provides instructions for setting up a connector server using the Identity Cloud Admin UI. You can also create a connector configuration over REST.

Connectors can read data in your tenant, and can read data in an external resource. An external resource is an app or service that runs on a resource server outside your tenant. Use connectors to convert your identity profiles, as well user accounts in a resource server, into a format that both data stores can use.

For a quick take, see About Identity Cloud connectors on this page.

Before you begin

Before you can make a connection, you have to register a remote connector server with your tenant. You also need to have a connector service up and running.

Here’s an overview of the steps to take:

  1. Register a remote server.

  2. Download a remote server.

  3. Configure the remote server to connect to Identity Cloud.

  4. Install and configure a connector.

  5. Create a mapping between identities in Identity Cloud and identities in your identity resource server.

  6. (Optional) If you plan to set up load balancing or failover, then register a remote server cluster.

Register a remote server

  1. In the Identity Cloud Admin UI, go to Identities > Connect > Connector Servers.

  2. Click + New Connector Server.

  3. In the New Connector Server dialog box, provide the remote server details:

    • Name: This name is displayed in the Connector Servers list.
      Use only lowercase letters and numerals. No special characters or spaces allowed.

  4. Click Save.

When the remote server is successfully registered, you’ll see links to the Next Steps. Be sure to open each link in a different window or tab so have you always have access to the Next Steps dialog box.

connector next steps

Completing the Next Steps

1 Reset the client secret

Identity Cloud creates an OAuth 2.0 client for you, and opens its profile.

client secret

  1. Click Reset to change the client secret.

  2. In the Reset Client Secret dialog box, enter any string to serve as a password.

  3. Read the warning, and then click Save.

2 Download a remote server

You’re directed to the Identity Cloud connectors download page.

  1. Download the Remote Connector Server (Java).

    Download the OpenICF package to the host that will run the connector server.
    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, you could run the connector server on a host that’s dedicated to only connectors.

  2. Configure the remote server.

3 Install and configure a connector

You’re directed to the Supported Connectors page.

(Optional) If the connector you want to use is not bundled with the remote server you downloaded in Next Step 2, you’ll need these instructions. Choose a connector, and follow the instructions for downloading and installing it.

After you complete the Next Steps, click Done.

Configure a remote server

  1. Unpack the OpenICF package you downloaded from the IDM Connectors download page.

  2. Edit the file. details:
    1. Add the OAuth2 Client credentials used to obtain an OAuth2 token. The client uses the Client Credentials grant type.

      • connectorserver.clientId=RCSClient
        Identity Cloud created this OAuth 2 client for you.

      • connectorserver.clientSecret=<client-secret>
        Use the OAuth 2 client secret you entered for RCSClient.

    2. Uncomment these settings and edit them for your tenant:

      • connectorserver.url
        This is the Identity Cloud OpenICF endpoint.
        Use wss over HTTPS so the client can obtain a bearer token through OpenID.

        • In staging and production environments, use three URLs in a space-delimited list. Example:
          connectorserver.url=wss://<tenant-name> wss://<tenant-name> wss://<tenant-name>.io/openicf/2

        • In a development environment, use only one URL. Example:

      • connectorserver.connectorServerName=<remote-server-name>
        This is the remote server name you set through the Identity Cloud Admin UI. Be sure the name includes only lowercase letters and numerals. No special characters or spaces allowed.

      • connectorserver.pingPongInterval=60
        The WebSocket Ping/Pong interval (seconds).

      • connectorserver.housekeepingInterval=20
        The WebSocket connections housekeeping interval (seconds).

      • connectorserver.groupCheckInterval=900
        WebSocket groups check interval, in seconds.

      • connectorserver.webSocketConnections=3
        Specifies the number of sockets the connector server will establish and maintain to each IDM it connects to.

      • connectorserver.connectionTtl=3000
        WebSocket connection’s time to live (seconds).

      • connectorserver.newConnectionsInterval=10
        Time between new connections (seconds).

      • connectorserver.tokenEndpoint=https://<tenant-name>
        Token endpoint to retrieve access token.

      • connectorserver.scope=fr:idm:*
        OAuth2 token scope.

      • connectorserver.usessl=true
        Enables SSL.

      • connectorserver.loggerClass=org.forgerock.openicf.common.logging.slf4j.SLF4JLog

  3. When you’re satisfied with your changes, save the file.

  4. Start the remote server on the OAuth 2.0 client:


    bin\ConnectorServer.bat /run


    bin/ /run

  5. To verify that the connection is working, view the remote server status in the Remote Servers list.

Create a mapping

Create a mapping between identities in Identity Cloud, and identities in your identity resource server.

  1. In the Identity Cloud Admin UI, go to Native Consoles > Identity Management.

  2. In the IDM Admin UI, click Create Mapping.
    For detailed information and instructions, see Configure a Resource Mapping.

Once you’ve tested your mapping configuration per the instructions, you can make connections for synchronizing and provisioning user profiles.

Register a server cluster

This is optional. Use a cluster of remote servers when you want to set up load balancing or failover among multiple resource servers.

  1. In the Identity Cloud Admin UI, go to Identities > Connect > Server Clusters.

  2. Click + New Server Cluster.

  3. Provide Server Cluster Details:

    Connector Cluster Details
    • Name: Identifier to display in the Server Clusters list.

    • Algorithm:

      • Choose Failover if you want requests to be redirected to a designated server only when the primary server fails.

      • Choose Round Robin if you want to continuously load-balance among two or more servers regardless of service status.

  4. Click Next.

  5. In the Choose Servers dialog box, enable the connectors you want to include in the server cluster.

    All connectors in a server cluster must be of the same type such as LDAP, Salesforce, and so forth. If a server cluster contains a connector that is not the same type as the others in the cluster, the different connector will not work.

  6. Click Create Cluster.

Synchronize passwords

You can synchronize hashed user passwords from your ForgeRockĀ® Directory Services deployment into Identity Cloud.

Password synchronization relies on an LDAP connector configured to synchronize accounts from your DS servers. Identity Cloud password synchronization does not use a password synchronization plugin. Instead, it synchronizes hashed passwords as strings in the same way it synchronizes other LDAP attributes.

This feature depends on having compatible one-way hash password storage schemes in Identity Cloud and in your DS password policies. DS servers in Identity Cloud verify user-provided plaintext passwords against the password hash, just as the DS servers in your deployment.

  1. Verify that your DS service stores the passwords you want to synchronize only with DS password storage schemes that are also enabled in Identity Cloud.

    The following DS password storage schemes are enabled in Identity Cloud:

    • Bcrypt

    • PBKDF2

    • PBKDF2-HMAC-SHA256

    • PBKDF2-HMAC-SHA512

    • Salted SHA-256

    • Salted SHA-512

    • SCRAM-SHA-256

    • SCRAM-SHA-512

  2. Verify that account synchronization works properly from your DS service to Identity Cloud.

    For example, modify a test user’s entry in your DS server, and check that the corresponding account in Identity Cloud is correctly updated after reconciliation runs.

  3. In the native IDM Admin UI, configure the LDAP connector to synchronize userPassword attributes as strings:

    1. Delete __PASSWORD__ from the list of LDAP connector properties.

    2. Add userPassword with Native type: string and Run as User enabled.

  4. In the native IDM Admin UI, configure the mapping from your remote DS system resource to Identity Cloud managed users:

    1. Map userPassword in your remote DS system resource to password in managed users.

    2. Set the transformation script for the synchronization to the following inline script, of type JavaScript:

      // Set the text of {ds_abbr} userPassword as the value of the password:
      if (source != null) {
        var base64 =;
        decodedTarget = new;
        target = decodedTarget;
  5. Verify that password synchronization is working correctly.

    For example, modify a test user’s password in your DS server, and check that the user can authenticate in Identity Cloud after reconciliation runs.

About Identity Cloud connectors

Your platform administrators use Identity Cloud by accessing your tenant. But, non-administrators and customers sign in to applications other than Identity Cloud itself. Apps and services that run and store data outside your tenant exist as external resources relative to Identity Cloud.

Identity Cloud provides connectors to synchronize your identity profiles with data stored in your resource servers.

Connectors work differently based on the capabilities of the connected resource server. For a summary of supported connectors and their capabilities, see Supported Connectors.

Syncing and provisioning

Here’s how Identity Cloud synchronizes user data. In this diagram, an identity resource server hosts an app and a data store containing user accounts. The resource server also hosts a connector server. The connector server runs a connector.

When you edit a user’s account on the resource server, the connector makes the change in the user’s profile in your tenant.

idcloud connector server

The opposite also happens. When you edit a user’s profile in your tenant, the connector makes the change in the user’s account in your resource server. For a quick take on Identity Cloud syncing and provisioning, see a related example in "Assignments".

Data reconciliation

Identity Cloud reconciles data when changes occur in either your identity profiles or in user accounts stored in resource servers.

An Identity Cloud connector first compares an identity profile to its corresponding user account in the resource server. If conflicting information exists, Identity Cloud resolves the conflicts based on your preferences. Then Identity Cloud updates both the identity profile and the user account.

Load balancing and failover

Use a connector server cluster (a cluster of connector servers) when you want to set up load balancing or failover. A connector server cluster connects to multiple resource servers.

When you configure the connector server cluster for load balancing, Identity Cloud distributes incoming authentication or authorization requests among the clustered servers. The connector service determines where a request is directed. Request traffic flows evenly, and no single connector works faster or more slowly than others in the server cluster. This ensures that requests are handled with the greatest efficiency.

When you configure connector servers for failover, if one resource server stops, then your Identity Cloud redirects requests to a standby resource server. This ensures that your end users don’t experience a loss of service. When the stopped resource server restarts, Identity Cloud directs requests to the restarted server.

More information

For a deep dive, see the following documents: