Synchronize users between Salesforce and IDM

The Salesforce connector enables provisioning, reconciliation, and synchronization between Salesforce and IDM.

This sample shows how to synchronize Salesforce user accounts and managed users in the IDM repository. You can use either the admin UI, or the command line to run this sample. Both methods are outlined in the sections that follow.

Prepare the sample

Configure your Salesforce organization.

To test this sample you must have an existing Salesforce organization, a Salesforce developer account, and a Connected App with OAuth enabled. For instructions on setting up a Connected App, see the corresponding Salesforce documentation. When you have set up the Connected App, locate the Consumer Key and Consumer Secret. You will need these details to configure the connector.

When you set up your Connected App, make sure that you include the following scopes, even if you plan to use the "Full access (full)" scope:
- Access and manage your data (api).
- Access your basic information (id, profile, email, address, phone).
- Perform requests on your behalf at any time (refresh_token, offline_access).
Prepare IDM as described in Prepare IDM, then start the server with the configuration for the Salesforce sample:
```
/path/to/openidm/startup.sh -p samples/sync-with-salesforce
```

Run the sample

You can run the sample using the admin UI, or over the command line. Using the admin UI is recommended because the command-line example is significantly more complex for this sample:

Use the admin UI

Log in to the admin UI at the URL https://localhost:8443/admin as the default administrative user (openidm-admin) with password openidm-admin.

Enable the Salesforce connector by completing the authentication details as follows. You will need the Consumer Key and Consumer Secret that you obtained from your Connected App configuration.

Select the Salesforce connector, and click Enable.

Under Base Connector Details, select Production, Sandbox, or Custom to set your Login URL.

The Login URL is the OAuth endpoint that will be used to make the OAuth authentication request to Salesforce.

The default endpoint for a production system is https://login.salesforce.com/services/oauth2/token. The default endpoint for a sandbox (test) system is https://test.salesforce.com/services/oauth2/token.

When you create your connected app, you are instructed to wait 2-10 minutes for the settings to propagate across all the Salesforce data centers. If you are using a Salesforce test tenant, such as https://eu26.lightning.force.com, you can specify a custom URL here and enter the FQDN of the test tenant. This will enable you to test the connector without waiting for the new app settings to be propagated.

Enter your Consumer Key and Consumer Secret, then select Save to update the connector configuration.
The connector now attempts to access your Salesforce organization.
Enter your Salesforce login credentials.
On the permission request screen click Allow, to enable IDM to access your Salesforce Connected App.

To test reconciliation, select Configure > Mappings.

There are two configured mappings, one from Salesforce to the IDM repository (managed/user) and one from the repository to Salesforce.
Select Reconcile on the first mapping.

The reconciliation operation creates the users that were present in your Salesforce organization in the IDM repository.
Retrieve the users in the repository by selecting Manage > User.

The repository should now contain all the users from your Salesforce organization.
To test the second mapping (from IDM to Salesforce), update any user in the repository.

By default, implicit synchronization is enabled for mappings from the managed/user repository to any external resource. This means that when you update a managed object, any mappings defined in the sync.json file that have the managed object as the source are automatically run to update the target system. For more information, see Resource mapping.

To confirm that the implicit synchronization has been successful, check the updated user record in Salesforce.

Use the command line

This section breaks the sample into two tasks:

Configure the connector.
Test the configuration.

Configure the Salesforce connector

Retrieve all the required configuration properties, as described in connector-reference:salesforce.adoc#salesforce-provisioner.

Edit the configurationProperties object in the Salesforce connector configuration file (openidm/samples/sync-with-salesforce/conf/provisioner.openicf-salesforce.json ) to include your Salesforce login URL, Consumer Key and Consumer Secret, refresh token, and instance URL.

Set the enabled property to true to enable the connector.

The relevant excerpts of the provisioner.openicf-salesforce.json file are as follows:

{
    "enabled" : true,
...
    "configurationProperties" : {
        "connectTimeout" : 120000,
        "loginUrl" : https://login.salesforce.com/services/oauth2/token,
        "idleCheckInterval" : 10000,
        "refreshToken" : "5Aep861KIwKdekr90I4iHdtDgWwRoG7O_6uHrgJ.yVtMS0UaGxRqE6WFM...",
        "clientSecret" : "4850xxxxxxxxxxxxx425",
        "clientId" : "3MVG98dostKihXN7Is8Q0g5q1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxP...",
        "instanceUrl" : "https://example-com.cs1.my.salesforce.com",
        "version" : 44
    }
...

Check that your connector configuration is correct by testing the status of the connector, over REST.

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/system?_action=test"
{
  "name": "salesforce",
  "enabled": true,
  "config": "config/provisioner.openicf/salesforce",
  "connectorRef": {
    "bundleVersion": "1.5.20.15",
    "bundleName": "org.forgerock.openicf.connectors.salesforce-connector",
    "connectorName": "org.forgerock.openicf.connectors.salesforce.SalesforceConnector"
  },
  "displayName": "Salesforce Connector",
  "objectTypes": [
    "__ALL__",
    "User"
  ],
  "ok": true
}

Run reconciliation

The mapping configuration file (sync.json) for this sample includes two mappings, systemSalesforceUser_managedUser, which synchronizes users from the Salesforce with the IDM repository, and managedUser_systemSalesforceUser, which synchronizes changes from the repository to Salesforce.

Reconcile the repository over the REST interface by running the following command:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request POST \
"http://localhost:8080/openidm/recon?_action=recon&mapping=systemSalesforceUser_managedUser&waitForCompletion=true"
{
  "state": "SUCCESS",
  "_id": "8a6281ef-6faf-43dd-af5c-3a842b38c468"
}

The reconciliation operation returns a reconciliation run ID and the status of the operation. Reconciliation creates user objects from Salesforce in the IDM repository, assigning the new objects random unique IDs.

Retrieve the managed users in the repository:

curl \
--header "X-OpenIDM-Username: openidm-admin" \
--header "X-OpenIDM-Password: openidm-admin" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"http://localhost:8080/openidm/managed/user?_queryFilter=true&_fields=_id"
{
  "result": [
    {
      "_id": "180c6686-b098-460a-a246-4e03fa0b8eb2",
      "_rev": "00000000cfe1fccf"
    },
    {
      "_id": "d0c25a0c-f7e6-4249-9c81-e546728f5bdd",
      "_rev": "000000000828e760"
    },
    {
      "_id": "25181ab3-0d40-4f80-96d6-d620eef7b6da",
      "_rev": "0000000038b6e342"
    }
  ],
  "resultCount": 3,
  "pagedResultsCookie": null,
  "totalPagedResultsPolicy": "NONE",
  "totalPagedResults": -1,
  "remainingPagedResults": -1
}

The output displays that the users in the Salesforce data store have been created in the repository.

IDM 7.2.2