Identity Cloud

Sync identities

Before you can sync identities with a remote server or use load balancing and failover, you must register a remote server with your tenant.

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

Identity Cloud provides built-in connectors for synchronization with data stores in other cloud services.

Process overview

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

To configure connectors that aren’t built in to Identity Cloud, complete this list of tasks in order:

  1. Register a remote server.

  2. Change the client secret by resetting it.

  3. Download a remote server from Backstage.

  4. Install and configure a connector, if needed.

    You can also create a connector configuration over REST.

  5. Configure the remote server to connect to Identity Cloud (optional).

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

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

For troubleshooting advice, refer to the knowledge base article How do I troubleshoot the Java Remote Connector Service (RCS)?.

Tasks

Task 1: 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 are allowed.

  4. Click Save.

When the remote server is successfully registered, links display 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.

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

Task 3: Download a remote server

You’re directed to the IDM Cloud Connectors download page. You must sign in to Backstage to view this page and download the connectors.

  1. Download the Remote Connector Server to the host that will run the connector server.

    ForgeRock recommends using the Java version of the Remote Connector Server. Only download the .NET version if you need to use a PowerShell connector. For more information about the differences between the RCS types, refer to Install a Remote Connector Server (RCS).

    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.

Task 4: Install and configure a connector

If the connector you want to use is not bundled with the remote server you downloaded in Task 2, you’ll need these instructions. Follow the instructions in the ICF documentation to download and install the remote connector you need.

After you complete the Next Steps, click Done in the Next Steps window.

Task 5: Configure a remote server

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

  2. Edit the ConnectorServer.properties file.

    ConnectorServer.properties 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-env-fqdn>/openicf/0 wss://<tenant-env-fqdn>/openicf/1 wss://<tenant-env-fqdn>/openicf/2

        • In a development environment, use only one URL. Example:
          connectorserver.url=wss://<tenant-env-fqdn>/openicf/0

      • 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 are allowed.

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

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

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

      • connectorserver.webSocketConnections=3
        Specifies the number of sockets the connector server establishes and maintains to each Identity Cloud (IDM) backend instance.

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

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

      • connectorserver.tokenEndpoint=https://<tenant-env-fqdn>/am/oauth2/realms/root/realms/alpha/access_token
        Token endpoint to retrieve access token.

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

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

      You don’t need to set the connectorserver.usessl property; the remote server determines connection security from the value of the connectorserver.url property.

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

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

    • Windows

    • Linux

    bin\ConnectorServer.bat /run
    bin/ConnectorServer.sh /run

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

Task 6: 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, refer to Configure a resource mapping.

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

Task 7: 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:

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

    Every connector associated with a server cluster must have an identical set of JAR files and scripts in its /path/to/openicf/lib directory. All JAR files must be at the same version. If you make any changes to the JAR files and scripts in this directory, you must propagate the changes to all the other connectors in the server cluster.

  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 updated correctly 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:

      // Set the text of DS userPassword as the value of the password:
if (source != null) {
  var base64 = Packages.org.forgerock.util.encode.Base64url;
  decodedTarget = new Packages.java.lang.String(base64.decode(source));
  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

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, refer to the ICF documentation.

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, refer to a related example in "Assignments".

Data reconciliation

Identity Cloud reconciles data when changes occur in 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 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 your end users don’t experience a loss of service. When the stopped resource server restarts, Identity Cloud directs requests to the restarted server.

Deactivate the RCS OAuth 2.0 client

The RCS OAuth 2.0 client is activated by default. If you do not need to synchronize your tenant data using a connector, you can deactivate the client:

  1. In the Identity Cloud admin UI, go to OAuth2 Clients.

  2. Click RCSClient.

  3. Click check_circle Active, then select power_settings_new Inactive.

  4. The client is immediately deactivated.

If you deactivate the RCS OAuth 2.0 client, you can reactivate it at any time.

More information

For a deep dive, refer to the following documents:

Copyright © 2010-2024 ForgeRock, all rights reserved.