Salesforce Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

The Salesforce connector lets you provision, reconcile, and synchronize users between Salesforce and the IDM managed user repository.

This chapter describes how to install and configure the Salesforce connector, and how to perform basic tests to ensure that it's running correctly.

For a complete example that includes the configuration required to synchronize users with this connector, see Synchronize Users Between Salesforce and IDM.

Before You Configure the Salesforce Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

The instructions in this chapter assume that you have an existing Salesforce organization, a Salesforce administrative 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.

The Salesforce connector is bundled with IDM and has no specific installation requirements.

Configure the Salesforce Connector

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

The easiest way to configure the Salesforce connector is through the Admin UI:

Configure the Salesforce Connector Through the UI

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

Log in to the Admin UI at https://localhost:8443/admin (substitute localhost for the host on which your IDM instance is running).
Select Configure > Connectors, and click New Connector.
Enter a Connector Name (for example, Salesforce) and select Salesforce Connector - 1.5.20.12 as the Connector Type.
Supply the Login URL, Consumer Key, Consumer Secret and click Save.
The Login URL is the OAuth endpoint that will be used to make the OAuth authentication request to Salesforce.
Note
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 lets you test the connector without waiting for the new app settings to be propagated.
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.
When your connector is configured correctly, the connector displays as Active in the UI.

Configure the Salesforce Connector With a Configuration File

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

IDM provides a sample connector configuration file in the /path/to/openidm/samples/example-configurations/provisioners directory.
Copy this sample file (provisioner.openicf-salesforce.json) to your project's conf directory, and set at least the following properties:
```
"configurationProperties" : {
    "loginUrl" : "loginURL",
    "clientSecret" : "clientSecret",
    "clientId" : "clientId",
    "refreshToken" : "refreshToken"
    "instanceUrl" : "instanceURL",
}
```
loginUrl
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.
clientSecret
The Consumer Secret associated with your Connected App.
clientId
The Consumer Key associated with your Connected App.
refreshToken and instanceURL
The Admin UI obtains these properties on your behalf. If you are configuring the connector manually, obtain the refresh token and instance URL from salesforce.com as follows:
Point your browser to the following URL:
SALESFORCE_URL/services/oauth2/authorize?response_type=code&client_id=CONSUMER_KEY&redirect_uri=REDIRECT_URI&scope=id+api+refresh_token
Where:
SALESFORCE_URL is one of the following:
A production URL (https://login.salesforce.com)
A sandbox URL (https://test.salesforce.com)
A custom Salesforce MyDomain URL, such as:
https://ic-example-com--SUP1.cs21.my.salesforce.com
CONSUMER_KEY is the Consumer Key associated with the Connected App that you created within your Salesforce organization.
REDIRECT_URI is the IDM URI Salesforce should redirect to during authentication. It must match the Redirect URI specified within your Salesforce Connect App configuration, for example:
https://localhost:8443/
You are redirected to Salesforce, and prompted to give this application access to your Salesforce account. When you have given consent, you should receive a response URL that looks similar to the following:
https://localhost:8443/admin/index.html#connectors/edit//&code=aPrxJZTK7Rs03PU634VK8Jn9o_U3ZY1ERxM7IiklF...
The &code part of this URL is an authorization code, that you need for the following step.
Caution
This authorization code expires after 10 minutes. If you do not complete the OAuth flow within that time, you will need to start this process again.
Copy the authorization code from the response URL and use it as the value of the code parameter in the following REST call. The consumer-key, redirect-uri, and SALESFORCE_URL must match what you used in the first step of this procedure:
curl \ --verbose \ --data "grant_type=authorization_code" \ --data "client_id=consumer-key" \ --data "client_secret=consumer-secret" \ --data "redirect_uri=https://localhost:8443/" \ --data "code=access-token-code" \ "SALESFORCE_URL/services/oauth2/token" { "access_token": "00DS0000003K4fU!AQMAQOzEU.8tCjg8Wk79yKPKCtrtaszX5jrHtoT4NBpJ8x...", "signature": "2uREX1lseXdg3Vng/2+Hrlo/KHOWYoim+poj74wKFtw=", "refresh_token": "5Aep861KIwKdekr90I4iHdtDgWwRoG7O_6uHrgJ.yVtMS0UaGxRqE6WFM77W7...", "token_type": "Bearer", "instance_url": "https://example-com.cs1.my.salesforce.com", "scope": "id api refresh_token", "issued_at": "1417182949781", "id": "https://login.salesforce.com/id/00DS0000003K4fUMAS/00530000009hWLcAAM" }
The output includes the refresh_token and the instance_url that you need to configure the connector.
Set "enabled" : true to enable the connector.
Save the connector configuration.

Test that the configuration is correct 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/system/salesforce?_action=test"
{
  "name": "salesforce",
  "enabled": true,
  "config": "config/provisioner.openicf/salesforce",
  "connectorRef": {
    "bundleVersion": "[1.5.0.0,1.6.0.0)",
    "bundleName": "org.forgerock.openicf.connectors.salesforce-connector",
    "connectorName": "org.forgerock.openicf.connectors.salesforce.SalesforceConnector"
  },
  "displayName": "Salesforce Connector",
  "objectTypes": [
    "__ALL__",
    "User"
  ],
  "ok": true
}

If the command returns "ok": true, your connector has been configured correctly, and can authenticate to Salesforce.

Implementation Specifics

Important

Connectors continue to be released outside the IDM release. For the latest documentation, refer to the ICF documentation.

For PATCH requests, a connector can potentially add, remove, or replace an attribute value. The Salesforce connector does not implement the add or remove operations, so a PATCH request always replaces the entire attribute value with the new value. Salesforce does not support multi-valued attributes.
Attributes themselves cannot be removed from Salesforce. The connector therefore performs an update with "" as the value of the attribute being removed. This sets the value of the removed attribute to null.
Note
Salesforce does not support application user DELETE requests.
The Salesforce connector supports any Salesforce object that is available to the API. To check which objects are available, log in to Salesforce Workbench to access the API explorer. This URL points to Version 49 of the API. Adjust the URL for the latest API version.
Because the number of Salesforce objects is potentially very large, the Salesforce connector configuration includes a supportedObjectTypes property that lets you specify the objects you want to support. The connector checks the metadata in Salesforce for each of the objects you list in this property, and dynamically builds the required schema. The sample connector configuration file (provisioner.openicf-salesforce.json) generates the schema only for the User object:
```
{
    ...
    "configurationProperties": {
        ...
        "supportedObjectTypes": [
            "User"
        ]
    },
}    
```
You can add any object to the list of supportedObjectTypes, and the connector will build the schema for that object.
The Salesforce API restricts how query results can be paged. The default, and maximum page size is 2000. The minimum page size is 200. The Salesforce API does not guarantee that the requested page size is the actual page size. Returned results might vary, to maximize performance.
For example, the following query (with "pageSize=1") might return more than one user if more than one user exists in Salesforce:
http://localhost:8080/openidm/system/salesforce/user?_queryId=query-all-ids&_pageSize=1
For more information, see the Salesforce documentation.

OpenICF Interfaces Implemented by the Salesforce Connector

The Salesforce Connector implements the following OpenICF interfaces.

Create

Creates an object and its uid.

Delete

Deletes an object, referenced by its uid.

Schema

Describes the object types, operations, and options that the connector supports.

Script on Connector

Enables an application to run a script in the context of the connector. Any script that runs on the connector has the following characteristics:

The script runs in the same execution environment as the connector and has access to all the classes to which the connector has access.
The script has access to a connector variable that is equivalent to an initialized instance of the connector. At a minimum, the script can access the connector configuration.
The script has access to any script-arguments passed in by the application.

Search

Searches the target resource for all objects that match the specified object class and filter.

Sync

Polls the target resource for synchronization events, that is, native changes to objects on the target resource.

Test

Tests the connector configuration. Testing a configuration checks all elements of the environment that are referred to by the configuration are available. For example, the connector might make a physical connection to a host that is specified in the configuration to verify that it exists and that the credentials that are specified in the configuration are valid.

This operation might need to connect to a resource, and, as such, might take some time. Do not invoke this operation too often, such as before every provisioning operation. The test operation is not intended to check that the connector is alive (that is, that its physical connection to the resource has not timed out).

You can invoke the test operation before a connector configuration has been validated.

Update

Updates (modifies or replaces) objects on a target resource.