Connect 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 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 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 Admin UI, go to Identities > Connect > Remote Servers.

  2. Click + New Remote Server.

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

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

    • Use SSL: Enable this option to add Secure Socket Layer security.

  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 ForgeRock IDM Connectors download page.

Choose one of the two Connector Servers:

  • Choose Remote Connector Server (.NET) if you’re connecting to an Active Directory identity server.

  • Choose Remote Connector Server (Java) if you’re connecting to any supported identity resource server except Active Directory.

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, that’s dedicated to hosting only connectors.

3. Install and configure a connector.

You’re directed to the Supported Connectors page in the ForgeRock IDM Connector’s Guide.

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

The very last step is to configure the remote server.

Configure a remote server

  1. Unpack the OpenICF package you downloaded in Next Step 2.

  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=<YourClientSecret>
        Use the OAuth 2 client secret you entered for RCSClient.

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

      • connectorserver.tokenEndpoint=https://openam-<YourTenantName>.forgerock.io/am/oauth2/realms/root/realms/alpha/access_token
        Token endpoint to retrieve access token.

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

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

      • connectorserver.url=wss://openam-<YourTenantName>.forgerock.io/openicf/0 wss://openam-<YourTenantName>.forgerock.io/openicf/1 wss://openam-<YourTenantName>.io/openicf/2
        Cloud OpenICF endpoint.

        ○  Use wss over HTTPS so the client can obtain a bearer token via OpenID.
        ○  Use multiple space-delimited URL entries. Multiple URLs ensure that disconnected websockets can reconnect properly.
      • connectorserver.pingPongInterval=0
        The WebSocket Ping/Pong interval (seconds).

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

    3. Uncomment and edit the following settings:

      • connectorserver.usessl=true
        Enables SSL.

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

      • connectorserver.webSocketConnections=3
        Number of websocket connections to open. This is the number of URLs specified in the `connectorserver.url`property.

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

      • connectorserver.connectionTtl=88
        Websocket connection’s time to live (seconds).

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

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

    Windows

    bin\ConnectorServer.bat /run

    Linux

    bin/ConnectorServer.sh /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 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 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-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 = 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

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"   in the ForgeRock Identity Management Connectors Guide.

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 deep dive information see these sections of the ForgeRock Identity Management Connectors Guide: