Salesforce.com

The Salesforce.com connector enables provisioning/deprovisioning with Salesforce.com (SFDC). The section below describes how to deploy and configure the SFDC connector in your environment. The connector supports the REST interface for integration with SFDC. The connector supports the following functionality:

FeatureSupported
CRUD operations for userY
Password synchronizationY
User Lookup / SearchY
Bulk user import / synchronizationY

Prerequisites

Salesforce.com API version

This connector has been tested with SFDC REST API v39.0

Connector host

This connector requires a Linux host to operate. If you are deploying in a Kubernetes environment, the connectors will be deployed automatically. If you are using either the Docker or a RPM file distribution, then follow the steps described in the installation section.

Service account privileges

The connector will need a service account to communicate with SFDC. The service account should have the following privileges:

Privilege NameRequired
User with appropriate licensesY
Profile with API Enabled boxY

To turn on API Enabled, follow the steps below:

  • Login to SFDC
  • Go to Administration Setup -> Managed Users -> Create new Profile / "Edit" an existing user as shown in the image below

alt text

  • Go to Administrative Permissions section and select API Enabled box

alt text

Installing the connector

Based on the nature of your deployment, follow the proceedures below to deploy the connector.

Docker swarm

To start this connector in a Docker Swarm deployment, follow the steps described below:

  • Uncommment the following line in setup.sh file
setup.sh - #docker pull "openiamdocker/salesforce-connector-rabbitmq:debian-${OPENIAM_VERSION_NUMBER}-${BUILD_ENVIRONMENT}
  • Uncomment the following line in startup.sh file
#docker stack deploy --compose-file connectors/salesforce/docker-compose.yaml --with-registry-auth salesforce-connector

For the changes to take effect you will need to stop your OpenIAM containers and then run:

./setup.sh
./startup.sh

Kubernetes

In a Kubernetes deployment, this connector will be deployed automatically as part of the OpenIAM solution. No additional steps are required.

RPM Install

To run the connector via RPM, you need to download the jar file for this connector and run it using following command:

java -Dlogging.level.root=INFO -Dconfpath=/data/openiam/ -Dorg.openiam.connector.queue=SALESFORCE_Connector_1_Request -Dorg.openiam.connector.queueResponseName=SALESFORCE_Connector_1_Response -jar salesforce-connector-rabbitmq.jar>salesforce.out&

SALESFORCE_Connector_1 - default queue. If you create another connector config please update your configuration accordingly.

Use the command below to see the logs related to this connector:

tail -f salesforce.out

Register Connector in OpenIAM

The connector must be registered within OpenIAM for it to be operational. This process defines the message queue which will be used by the core OpenIAM services to communicate with the connector using the message below. To register the SFDC connector, login to the Webconsoole and follow the steps below:

  • Go to Provisioning -> Connector
  • If an entry for the Salesforce.com connector does not exist then click on Create new connector from the side menu
  • Complete the fields as shown in the table below
Connector configuration parameterDescription
Connector NameThis can be an descriptive name that will help you identify this connector such as: Salesforce.com
Metadata GroupingSelect Connector type
Metadata Type NameSelect Salesforce.com connector. This identifies the type of connector internally.
Connector QueueEnter SALESFORCE_Connector_1. This is the name of the queue which the connector is using to receive messages.

Security information needed to establish a connection

Generate a security token

Before we can establish a connection to SFDC using our connector, we must generate a security token which is used in the password field. You will need to do this on SFDC side.

When you create an account you will get your security token. If you lose this token, then you can generate new one using the steps below: For this you should login to your account and go to Personal Setup -> My Personal Information -> Reset My Security Token -> Reset Security Token

alt text

alt text

For additional information about generating a security token, please view: Salesforce.com security token

Client ID and Secret

If you plan to use the REST interface, you will also need to obtain the Client ID and Client Secret. You can obtain this from your tenant / account admin. This information can be obtained by:

  • Login to SFDC
  • Go to Create → Apps → Connected Apps -> click by name

alt text

  • Open the needed app and you will see the Consumer Key (Client ID) and Consumer Secret (Client Secret). These will be needed in the next step where we establish a connection from OpenIAM to SFDC.

alt text

Establishing a connection with your SFDC tenant

To establish a connection with your SFDC tenant, you must define a "Managed System" configuration by going to Provisioning -> Managed system in the Webconsole. As indicated earlier, the OpenIAM SFDC connector supports both REST and SOAP interfaces. Depending on the option you select, follow the steps below to define a managed system configuration.

OpenIAM Managed system configs REST:

Managed System FieldValue
Host URLhttps://[enter your tenant name].salesforce.com For example: https://mycorp.salesforce.com for example
API typeREST API
Login IdUsername
PasswordPassword + security token (like on word)
Grand TypeEnter password
Client IDClient ID
Client SecretClient Secret
API VersionEnter v39.0. This value is the REST API version

If the connection is successfully then in a few minutes you should see the connection healthcheck in 'Green'. If the healthcheck fails, it will be read and you will need to troubleshoot the connection further

Example of configured managed system:

alt text

Define the provisioning PolicyMap

The last step in the provisioning process is to define a policy map which determines how the connector is will populate each attribute for the User object. To create a new policy map, follow the steps below and then use the table below to determine how each attribute should be defined.

  • Go to Policy Map on the Managed system configuration used above
  • Click on the "Add" button and select Provision user from the drop down

Additional information about the fields and their use can be found in the SFDC docs at: Salesforce API Documentation

Field NameRequiredOOTB Groovy scriptValue
1AliasUser alias. Need to create custom field and get value from there. Can’t be longer than 8 characters
2DefaultGroupNotificationFrequencyNeed to set default value in groovy or create custom field with type select.
3DigestFrequencyNeed to set default value in groovy or create custom field with type select.
4EmailThis is set to the Primary email field in OpenIAM. Must be unique.
5EmailEncodingKeyNeed to set default value in groovy or create custom field with type select. By default this is UTF-8
6FirstNameNUser's first name. Not required in salesforce, but required in OpenIAM
7IsActiveThis attribute controls if the user is either active or disabled in SFDC. The default scripts use the Status in OpenIAM to determine this value.
8LanguageLocaleKeyNeed to set default value in groovy or create custom field with type select. By default en_US.
9LastNameUser lastname
10LocaleSidKeyNeed to set default value in groovy or create custom field with type select. By default en_US.
11PasswordUser password. Not need for provisioning. Only for reset password. If this field inactive, password anyway will be reset, but link with password will be sent to user. If this field active and we set a password, the password will be updated to inputted.
12ProfileIdNeed to create custom field. This field should contain ID of profile where the user should be added.
13TimeZoneSidKeyNeed to set default value in groovy or create custom field with type select. By default America/New_York.
14UsernamePrincipal. By default get value from primary email.
15UserPermissionsCallCenterAutoLoginNeed to set default value in groovy or create custom field with type select. By default false.
16UserPermissionsMarketingUserThis attribute is required in SFDC but is not in OpenIAM by default. Therefore, the value is in a groovy script. Alternatively, a custom field can defined. Default value is false.
17UserPermissionsOfflineUserThis attribute is required in SFDC but is not in OpenIAM by default. Therefore, the value is in a groovy script. Alternatively, a custom field can defined. Default value is false.
18UserPermissionsWirelessUserThis attribute is required in SFDC but is not in OpenIAM by default. Therefore, the value is in a groovy script. Alternatively, a custom field can defined. Default value is false.

All of these fields except FirstName, LastName, Email, Password, IsActive should be created as custom fields for user template. Most of them have default value defined in groovy script.

Connector Troubleshooting Tips

Important:

When provisioning a newly created user, you cannot assign a password to the user as none of the API's allow you to manage the field to send emails to the new user with password. The user must first be created without a password and then updated with the password. The password depends on the "Password" field in the Policy Map. After the password has been set, the user won't be able to login for about 5min. Please wait as this delay is from the Salesfoce.com side.

Errors:

After assigning a password to the user and then logging in to the Salesforce.com UI for the first time, the user will be asked to change their password. If you cancel this reset password, and then set new password from API you will see this exception below. However, the password will be set anyways.

[UnexpectedErrorFault [ApiFault exceptionCode='UNKNOWN_EXCEPTION' exceptionMessage='invalid repeated password' extendedErrorDetails='{[0]}']