1. Unpack the contents of the .zip file into the install location.

   $ cd /path/to
   $ unzip ~/Downloads/salesforce_identity_connect_linux.zip

2. Run the setup script.

   $ cd /path/to/salesforceIdConnect
   $ ./setup.sh

3. Enter the SSL port to listen on for the Identity Connect user interface. The default is 8443.

   If you are running Windows Firewall, make sure that inbound connections to this port are not blocked.

4. Enter y to have the Identity Connect server start immediately after setup, and run in the background.

   When Identity Connect runs in the background, any log messages are output to the file /path/to/salesforceIdConnect/logs/console.out.

   If you select not to have the server start immediately, you must start Identity Connect manually, using the startup.sh script. In this case, log messages are output to the terminal in which you started Identity Connect. To redirect log messages to console.out, follow the instructions in Section 2.2, "Stopping and Restarting Identity Connect".

5. Point your browser to https://hostname.domain:8443/admin/, (specifying an alternate port if you entered an alternate port during the setup).

   You will receive a warning about the website's security certificate if you have not replaced the default certificate with a trusted certificate. For more information, see Section 10.1, "Managing SSL Certificates".

1. Double-click the salesforce_identity_connect_win.zip file and select Extract all files.

2. In a command window, change to the install-location/salesforceIdConnect directory.

   C:\>cd install-location\salesforceIdConnect

3. Before you start the setup, consider the HTTPS port on which Identity Connect should listen. By default, Identity Connect listens on port 8443. To specify a different port, edit the openidm.port.https property in the conf/boot/boot.properties file before you start Identity Connect.

4. Run the startup.bat script.

   C:\install-location\salesforceIdConnect\>startup.bat

   Messages are output to the Felix shell in the command window in which you launched Identity Connect.

5. Point your browser to https://hostname.domain:8443/admin/, (specifying an alternate port if you changed the default port).

   You will receive a warning about the website's security certificate if you have not replaced the default certificate with a trusted certificate. For more information, see Section 10.1, "Managing SSL Certificates".

1. Unpack the Identity Connect .zip file, as described previously, and change to the bin directory:

   C:\>cd install-location\salesforceIdConnect\bin

2. Launch the Identity Connect service, with the following command:

   C:\install-location\salesforceIdConnect\bin>install-service.bat
   Identity Connect Service successfully installed as "IdentityConnect" service
       

3. Use the Windows Service manager to manage the Identity Connect service.

   

4. Change the user account for this service from the default (local system) account to an account with administrative privileges. The local system account has limited permissions and an Identity Connect service that runs with this account will encounter problems during synchronization.

   To change the user account:

   • Double click the "IdentityConnect" service in the Windows Service manager.

   • Select the Log On tab.

   • Select This Account and browse for an Active Directory administrative account.

   • Enter the password for the administrative account.

     

   • Click Apply to save the changes.

5. Use the Windows Service Manager to start, stop, or restart the service.

To run Identity Connect as a UNIX service:

1. If you have not already done so, install and set up Identity Connect, as described in Procedure 2.1, "To Install Identity Connect on UNIX-Like Systems".

2. Run the RC script.

   $ cd /path/to/salesforceIdConnect/bin
   $ ./create-idconnect-rc.sh
   idconnect script has been created in /path/to/salesforceIdConnect/bin
   To finish installation, copy the idconnect script into the /etc/init.d folder
   and run the following command:
   chkconfig --add idconnect
   
   To remove the service, run the following command:
   chkconfig --del idconnect

3. As a user with root privileges, copy the idconnect script to the /etc/init.d folder.

   $ sudo cp idconnect /etc/init.d/

4. As a user with root privileges, run the chkconfig --add command to install the Identity Connect service.

   $ sudo cd /etc/init.d/
   $ sudo chkconfig --add idconnect

5. Start the Identity Connect service.

   $ service idconnect start

   Alternatively, reboot the system to start the Identity Connect service automatically.

6. (Optional) To stop, restart, or check the status of the service, use the following commands:

   $ service idconnect stop

   $ service idconnect restart

   $ service idconnect status

7. (Optional) To remove the service, run the following command, as a user with root privileges:

   $ sudo chkconfig --del idconnect 

   Note that this command does not remove the Identity Connect application, but prevents it from being run as a service.

1. Stop Identity Connect, if it is running.

   $ cd /path/to/salesforceIdConnect
   $ ./shutdown.sh
   Stopping OpenIDM (81491)

2. Back up your existing configuration by zipping up the entire salesforceIdConnect directory, and the database, in the event that you are using an external repository.

   There is currently no way to revert a patch, so it is highly recommended that you back up your configuration and data before patching. Although the upgrade process does create an archive of the current configuration, this information is not sufficient to revert an upgraded installation.

3. Download and unzip the Identity Connect patch (salesforce_identity_connect_win_patch.zip for Windows systems and salesforce_identity_connect_linux_patch.zip for Linux systems).

4. Run the following command to apply the patch to your existing Identity Connect instance.

   $ cd ~/Downloads
   $ java -jar salesforceIdConnect-2.1.0-patch.jar /path/to/salesforceIdConnect
   Downloaded to salesforceIdConnect/patch/bin/salesforceIdConnect-2.1.0-patch.jar
   Apr 7, 2014 4:42:51 PM org.forgerock.patch.Archive initialize
   INFO: Created patch archive directory: salesforceIdConnect/patch/archive/20140407_164251
   Apr 07, 2014 4:42:51 PM HistoryLog INFO: Applying "Salesforce Identity Connect Patch",
    version=188.16
   Apr 07, 2014 4:42:51 PM HistoryLog INFO: Target: salesforceIdConnect,
    Source: file:/path/to/salesforceIdConnect-2.1.0-patch.jar
   Apr 07, 2014 4:43:02 PM HistoryLog INFO: Completed

5. If you are using an external MySQL repository, import the data definition language script for the Identity Connect upgrade into MySQL.

   $ cd /path/to/mysql
   $ ./bin/mysql -u root -p < \
     /path/to/salesforceIdConnect/db/scripts/mysql/upgrade-MySQL-schema.sql
   Enter password:
   $    

   Enter the root user password for the MySQL server.

6. If you are running Identity Connect as a Windows service, uninstall and reinstall the IdentityConnect service so that the appropriate changes are applied to the JVM startup parameters. To uninstall and reinstall the service, run these commands after the upgrade:

   C:\install-location\salesforceIdConnect\bin>launcher.bat /uninstall
   Service "IdentityConnect" removed successfully
   C:\install-location\salesforceIdConnect\bin>install-service.bat
   Identity Connect Service successfully installed as "IdentityConnect" service
        

7. Restart Identity Connect.

   $ cd /path/to/salesforceIdConnect
   $ nohup ./startup.sh > logs/console.out 2>&1&
   [1] 32548

   Caution

   Do not access the Administration console until you have observed the Completed post-upgrade tasks... message in the OpenIDM log file on startup. This is applicable to all deployments, but is particularly important in a clustered environment because the first patched instance (clustered-first) patches a number of configuration objects, including synchronization mappings and managed objects. These configuration patches are required before any subsequent nodes are started, to ensure a cohesive configuration across the cluster.

8. Before logging into Identity Connect, clear your browser cache. The browser cache contains files from the previous Identity Connect release, that might not be refreshed when you log into the UI of the new release.

Configure the Salesforce connector as follows:

1. Log in with the credentials of a user who belongs to one of the groups that you specified in the previous step.

   If your data source is an AD LDS instance, you must log in with the displayName of a user in one of these groups.

   The Salesforce connector setup page is displayed.

   

2. If this is the first time you are configuring Identity Connect, select New Organization (the only option available from the dropdown menu).

3. In the Salesforce login URL field, specify the OAuth endpoint that will be used to make the OAuth authentication request to Salesforce.

   • Select Production for a production system. The default endpoint for a production system is https://login.salesforce.com/services/oauth2/token.

   • Select Sandbox if you are verifying authentication on a test or sandbox organization. The default sandbox endpoint is https://test.salesforce.com/services/oauth2/token.

   • Select Custom to provide your own login URL.

4. Enter your consumer key and consumer secret, acquired during the configuration of the Identity Connect Connected App (see Section 2.5.1, "Setting Up a Connected App for Identity Connect").

   Make sure that the Callback URL specified on this screen is the one that you used when you set up the Identity Connect Connected App (https://hostname.domain:8443/admin/index.html#salesforceCallback by default).

   Click Update to validate the consumer key and secret with Salesforce.

   When you create a new Connected App, or update your Connected App in Salesforce, it takes some time (at least five minutes) for the data to be propagated through all the Salesforce servers. If you are setting up Identity Connect with a Connected App that you have just created, or if you have recently changed the Callback URL of your Connected App, you might receive an error when you attempt to validate the consumer key and consumer secret. Wait at least five minutes after creating or updating your Connected App before you attempt to set up Identity Connect with that App.

5. You are redirected to the Salesforce login page. Log in with your Salesforce credentials. Click Allow to authorize the remote application.

   

6. You are redirected to Identity Connect. A confirmation message is displayed: "Successfully retrieved token from Salesforce!".

   On networks with very high latency, the connection to Salesforce might timeout. In this case, you will see the following message: Establishing Salesforce connection is taking longer than expected.

   This issue is generally resolved by clicking Test Connection to reestablish the connection.

7. The Summary page is displayed, indicating your data source (Active Directory), the Salesforce organization that has been connected, and the status of any mapping that has been configured. At this stage, nothing has been mapped, so the mapping status indicates "0 Attributes Mapped".

   

   You are now ready to move on to the mapping configuration.

1. Before you start, make sure that you have configured a Connected App for the new organization, as described in Section 2.5.1, "Setting Up a Connected App for Identity Connect".

2. To connect to an additional Salesforce organization, click Salesforce Org on the Summary page.

   The dropdown list displays any previous organizations to which you have connected with this Identity Connect instance.

3. Select New Organization.

   

4. Follow the steps outlined in Section 3.2, "Configuring the Salesforce Connector" to complete the Salesforce connector configuration.

   When you have authorized the remote application, you are redirected to Identity Connect. You now have the option to continue with the new organization configuration, or to clone the configuration from an existing organization.

   Caution

   Creating a new organization configuration by cloning an existing configuration can save time, as you do not have to recreate the mapping rules for profiles and roles. However, you can clone an organization only if it originates from the same production organization as the original organization. For example, if you have configured a sandbox organization, you can clone this configuration for a new sandbox organization that is based on the same production organization, or for the production organization itself. Within the organization configuration, there are several references to ID values, that are valid only for organizations that are part of the same production organization "family". Attempting to clone an organization configuration across different production organization "families", will cause numerous errors.

   

   Note

   When you clone an organization from an existing organization, the new organization has the identical profile and role mappings that are configured for the existing organization. Permission set and group mappings are not cloned.

   By default, live updates and scheduled reconciliation are disabled for a newly cloned organization, regardless of the live update setting for the existing organization. Having updates disabled by default allows you to customize any changes to the new organization configuration before updates start to flow to your Salesforce data. You must manually enable live updates for the cloned organization, as described in Section 5.3, "Configuring the Synchronization Schedule".

5. To update the configuration for a particular organization at any stage, return to the Salesforce Org page and select the organization from the dropdown list. When you are configuring the mapping, synchronization, or SSO for your organization, make sure that the organization name displayed in the dropdown list refers to the organization that you are configuring.

Configure attribute mapping by following these steps:

1. On the Mapping page, select the Attributes tab.

2. Click on the Salesforce attribute whose value you want to define. For example, click on Email to specify the value that will be used for the Salesforce Email attribute.

3. The Attribute List tab enables you to specify an Active Directory attribute to be mapped directly. Enter the name of the attribute or type a few characters of the attribute name to select it from the list.

   

4. The Transformation Script tab enables you to specify how an Active Directory attribute is transformed to provide a value for the Salesforce attribute. The transformation script is a JavaScript that takes a source (Active Directory) attribute, and does something with its value to provide the Salesforce attribute value.

   For example, the sample transformation script source.mail ? source.mail.toLowerCase() : null takes the value of the mail attribute from Active Directory and converts it to lower case to provide the value of the Email attribute in Salesforce. If no value exists for the mail attribute, a null value is inserted as the value in Salesforce.

   The format of the transformation script depends on whether you have selected an attribute on the Attribute List tab. If you do not specify an attribute on the Attribute List tab, the entire object is regarded as the source, and you must include the attribute name in the script (for example, source.mail.toLowerCase();. If you specify an attribute on the Attribute List tab, that attribute is regarded as the source, so the transformation script would be source.toLowerCase();.

   

   By default, the manager attribute in Active Directory is mapped to the managerID attribute in Salesforce, using a transformation script. The transformation script locates the Active Directory manager property and looks up the manager's objectGUID, based on the value of his distinguishedName. The script then locates the corresponding SalesforceID of the manager, in the links table, and uses this ID to populate the managerID property in Salesforce.

   Note

   Active Directory attributes can be either single-valued or multi-valued. Multi-valued Active Directory attributes are stored as an array in the connector schema. If you are mapping a Salesforce attribute to a multi-valued Active Directory attribute, your transformation script must take this into account.

   For more information about single and multi-valued attributes, see the MSDN article on Single vs. Multiple Value Attributes.

5. For non-mandatory attributes, the Conditional Updates tab enables you to apply two types of conditions that determine specific situations in which an attribute in Salesforce will be updated.

   • You can define a conditional update script to prevent an attribute from being updated in Salesforce under certain conditions.

     A conditional update script takes the following form:

     object.attribute operator value
           

     where attribute refers to the source (Active Directory) attribute. The condition is based on the attribute value of the Active Directory entry. The corresponding attribute in Salesforce is updated only if the condition evaluates to true for that entry. The attribute name is case sensitive.

     For example, if all users based in Germany worked for a specific department, you might want to prevent any changes to these users' department attribute in Salesforce. In this example, you would apply a conditional update script to the department attribute in the mapping, which would filter out changes to this attribute for users whose country name (co) attribute was Germany. The following conditional update script on the department attribute would achieve this objective:

     object.co != "Germany"
           

     In other words, update this attribute in Salesforce only if the entry's country attribute is not Germany.

   • By default, Salesforce attribute values are set when a user is created, and when that user is updated. You can specify that the attribute value should be set only when the user is created, by selecting Only when creating a new user from the dropdown list on this tab.

     In this case, any updates to a user entry will not reset the Salesforce attribute value for that entry.

     Note that, regardless of the situation you select from this list, if you have defined a conditional update script that returns false for an entry, the attribute value will not be set for that entry.

   

6. The Default Values tab enables you to specify a default value that should apply for the Salesforce attribute in the event that the user does not have the corresponding attribute in his Active Directory user entry.

   The following example sets a user's CompanyName attribute to example.com in Salesforce, in the event that the user does not have a value for the company attribute in Active Directory.

   

7. If the default list of attributes that is presented is not sufficient, click Add Attribute to include additional Salesforce attributes in the mapping.

   The list of attributes in the Salesforce column is populated directly from the Salesforce data store. You cannot specify your own attributes here, but you can add attributes from the Salesforce list, if the default list does not meet your requirements.

8. To remove an attribute from the mapping, click the Delete icon next to that attribute. Mandatory attributes cannot be removed.

9. When the attribute mapping configuration is complete, click Save to save the mapping.

Configure profile mapping by following these steps:

1. On the Mapping page, select the Profile to AD Group tab.

2. On the Attribute List tab, select the LDAP attribute that is used to determine group membership. The default attribute is memberOf. Select a different attribute if your organization defines groups in a different way.

3. Select the Value Mapping tab to map profiles directly to Active Directory groups.

   The left hand column lists all possible Salesforce profiles. The right hand column indicates the Active Directory groups to which these profiles are mapped. No groups are mapped by default.

   

4. Click the edit icon adjacent to a Salesforce profile to map an Active Directory group to that profile.

   You can select more than one Active Directory group to map to the profile. The following selection maps all members of the Active Directory group "salesforceGroups" to the Standard User profile in Salesforce.

   

5. In the event of a user being allocated more than one Salesforce profile, based on the group mapping, you can specify an order of precedence to indicate which profile should be taken into account.

   Select the Value Precedence tab to specify the order of precedence. Click and drag the profiles so that they appear in the correct order.

6. When you have completed the initial mapping, select the Transformation Script tab to display the transformation that will be applied in order to map the ProfileId. You can also edit this script manually instead of using the preceding tab to generate it.

   Note that if you edit the transformation script manually, the Attribute List tab is not updated accordingly. In this case, Identity Connect uses the transformation that is specified on the Transformation Script tab and ignores the Attribute List tab.

7. Select the Default Values tab to specify the default Salesforce profile that will be applied to the user in the event that the user is not a member of any of the Active Directory groups specified here.

8. When you have completed the profile mapping, click Save to apply the mapping.

1. On the Mapping page, select the Permission Set to AD Group tab.

   Note that this tab is displayed only after you have clicked Save on the "Attributes" or "Profile to AD Groups" tab.

2. No permission sets are displayed by default. To add a permission set to be mapped, click Add Permission Set, select the permission set from the list, and click Submit.

   The list of permission sets displayed here are those that you have defined in your Salesforce organization. If you have not created any permission sets in Salesforce (apart from the default Identity Connect permission set), the Add Permission Set button is not displayed.

   

3. When you add new permission sets, the following message is displayed at the bottom of the Permission Set to AD Group page:

   Cached Permission Set Assignment Data is OUT OF DATE Update Now

   This message indicates that the permission set data that is stored in the Identity Connect repository is out of sync with the new permission set data.

   Click Update Now. This action launches a reconciliation operation that synchronizes the permission set data.

   Caution

   This reconciliation operation will not succeed if all the mapped permission sets are empty. Because the reconciliation operation does not succeed, the mapping continues to display OUT OF DATE, even after the Update Now operation is run. Therefore, before you run the Update Now operation, you must ensure that at least one Salesforce user is assigned to one of the selected permission sets.

   After the reconciliation operation has completed successfully, a message similar to the following is displayed:

   Cached Permission Set Assignment Data Last Updated June 23, 2014 12:57

4. Click the edit icon adjacent to the Salesforce permission set to map an Active Directory group to that permission set.

   You can select more than one Active Directory group to map to the permission set.

   The following image shows how the Manage Users permission set is mapped to the group of Domain Admins in Active Directory.

   

   Click Update to save the new mapping.

5. Repeat this procedure for each Salesforce permission set that you want to map.

1. Log in to Salesforce, and select Setup.

2. In the Administer section, expand the Company Profile menu and select Company Information.

3. Click Permission Set Licenses to display the total licenses purchased, the number of licenses in use (number of users provisioned) and the number of licenses remaining.

   

   If you have reached the maximum number of permission set licenses available, you must either buy additional licenses, or deactivate any defunct users in Salesforce (or disable them in Active Directory) before you can provision any new users.

1. On the Mapping page, select the SF Group to AD Group tab.

   Note that this tab is displayed only after you have clicked Save on the "Attributes" or "Profile to AD Group" tab.

2. No Salesforce groups are displayed by default. To add a Salesforce group to be mapped, click Add SF Group, select the Salesforce group from the list, and click Submit.

   The list of groups displayed here are those that have been defined in your Salesforce organization.

   

3. When you add new Salesforce groups, the following message is displayed at the bottom of the SF Group to AD Group page:

   Cached SF Group Membership Data is OUT OF DATE Update Now

   This message indicates that the Salesforce Group data that is stored in the Identity Connect repository is out of sync with the new Salesforce Group data.

   Click Update Now. This action launches a reconciliation operation that synchronizes the Salesforce Group data.

   Caution

   This reconciliation operation will not succeed if all the mapped Salesforce Groups are empty. Because the reconciliation operation does not succeed, the mapping continues to display OUT OF DATE, even after the Update Now operation is run. Therefore, before you run the Update Now operation, you must add at least one user to at least one mapped Salesforce Group.

   After the reconciliation operation has completed successfully, a message similar to the following is displayed:

   Cached SF Group Membership Data Last Updated June 23, 2014 13:24

4. Click the edit icon adjacent to the Salesforce group to map an Active Directory group to that Salesforce group.

   You can select more than one Active Directory group to map to the Salesforce group.

   The following image shows how the example-employees Salesforce group is mapped to the group of Employees in Active Directory.

   

   Click Update to save the new mapping.

5. Repeat this procedure for each Salesforce group that you want to map.

To configure the synchronization schedule, follow these steps:

1. Select the Sync tab for the Salesforce organization that you are configuring.

2. In the Scheduled Data Synchronization area, check Schedule Updates to specify a regular schedule for synchronization.

3. Select an update interval from the drop down list. Selecting minute, hour, day, and so on, specifies that updates are scheduled once every minute, hour or day. Selecting (n) days, (n) hours, and so on, enables you to specify the precise number of days, hours or minutes between each update.

4. Select Live Updates to indicate that data should be synchronized as soon as changes are made in Active Directory.

5. Click Save to save the synchronization configuration.

1. Change to the Identity Connect configuration directory.

   $ cd /path/to/salesforceIdConnect/conf

2. Using a text editor, edit the configuration file for your Salesforce organization (salesforce-org-id.json), adding the following properties:

   • "maxConnectionsPerHost" - the maximum number of simultaneous requests that a single Identity Connect browser session can make to each Salesforce site (Token and API)

   • "maxTotalConnections" - the total maximum number of connections maintained in the connection pool

   If these properties are not set, their default values are 10 and 20 respectively. Increase the values of these parameters to make more connections available to Identity Connect. Generally, if you are seeing connection errors, doubling the value of both parameters will prevent such errors.

   The following excerpt of an edited organization configuration file shows the parameters set to 20 and 40 respectively.

   $ more salesforce-00DS0000003K4fU.json
   {
       "enabled" : true,
       "configurationProperties" : {
           ...
           "idleCheckInterval" : 10000,
           "connectTimeout" : 120000,
           "maxConnectionsPerHost" : 20,
           "maxTotalConnections" : 40,
           "instanceUrl" : "https://example-com.my.salesforce.com",
           ....
       }
   }    
       

1. Log in to the Identity Connect administrative interface (for example https://connect.ad.example.com:8443/admin).

2. Click Settings in the top right corner and select the Authentication and Session tab.

3. Select Enable Integrated Windows Authentication.

4. Enter the following information:

   • Kerberos Distribution Center. Enter the FQDN or IP address of the Key Distribution Center (KDC), for example, host.ad.example.com.

     For a single domain, this is usually the host machine on which your Active Directory server is installed. For multiple domains, check with your IT administrator for the value of this field.

   • Kerberos Realm. Enter the name of the Kerberos realm, in upper case, for example, AD.EXAMPLE.COM.

     Note that this is the Kerberos realm described in Section 7.2.2, "Creating the Keytab File".

   • Service Principal Name (SPN). Enter the SPN of the Kerberos user account that you created previously. This value must match the output that was obtained during the keytab creation. In our example, this would be HTTP/connect.ad.example.com@AD.EXAMPLE.COM.

     If your service is behind a load balancer, enter the SPN of the load balancer user account here. In the previous example, this would be HTTP/lb.ad.example.com@AD.EXAMPLE.COM.

   • Upload Kerberos Keytab File. Click Browse to locate the keytab file that you created in the previous section.

     

     If your service is behind a load balancer, browse for the keytab file that you created for the load balancer host.

     In a clustered environment, you must copy this load balancer keytab file to the /path/to/salesforceIdConnect/security folder on all additional Identity Connect nodes.

You can customize various aspects of the login page that users see when they access the Identity Connect user interface (for example, at https://hostname.domain:8443/connect/). To change the UI theme, follow these steps:

1. Click the Settings menu at the top right of the Identity Connect administrative interface.

2. Select the Customize Theme tab.

3. Adjust the following settings, as required:

   • Background Color enables you to set the background color of the login page.

     To change the background color, click the Background Color dropdown list. Select the required color from the color panel, or enter the hex value of the required color, and click Choose.

   • Button Color enables you to set the color of all the buttons on the Identity Connect user interface.

     To change the button color, click the Button Color dropdown list. Select the required color from the color panel, or enter the hex value of the required color, and click Choose.

   • Logo enables you to select a custom logo to appear on the login screen and in the administrative interface.

     To select a custom logo, click Browse, and locate the image file.

4. When you have completed the customization, click Save to save your changes.

1. Click Settings at the top right of the Identity Connect window.

2. Select the Authentication and Session tab.

3. In the Reset Password Link field, enter the URL to which password reset requests should be sent.

1. Click Settings at the top right of the Identity Connect window.

2. Select the Authentication and Session tab.

3. In the Maximum session lifetime field, enter the maximum number of minutes that a session can be live, after the initial login.

4. In the Session idle timeout field, enter the maximum number of minutes that a session can be idle, before the user is logged out automatically.

1. Generate an obfuscated version of the password, by using the crypto bundle that is provided with Identity Connect:

   $ java -jar /path/to/salesforceIdConnect/bundle/openidm-crypto-2.1.0-IC-1.0.5.jar
   This utility helps obfuscate passwords to prevent casual observation.
   It is not securely encrypted and needs further measures to prevent disclosure.
   Please enter the password:
   OBF:1vn21ugu1saj1v9i1v941sar1ugw1vo0
   CRYPT:a8b5a01ba48a306f300b62a1541734c7

2. Paste either the obfuscated password (OBF:xxxxxxx) or the cryptographic key (CRYPT:xxxxxxx) into the conf/boot/boot.properties file. Comment out the regular key store password and remove the comment tags from the line that contains the obfuscated password or cryptographic key, depending on which one you have used:

   $ more conf/boot/boot.properties
   ...
   # Keystore password, adjust to match your keystore and protect this file
   # openidm.keystore.password=changeit
   openidm.truststore.password=changeit
   
   # optionally use the cli encrypt to obfuscate the password and set
   # openidm.keystore.password=OBF:1vn21ugu1saj1v9i1v941sar1ugw1vo0
   openidm.keystore.password=CRYPT:a8b5a01ba48a306f300b62a1541734c7
   ...

3. Restart Identity Connect.

   $ cd /path/to/salesforceIdConnect
   $ nohup ./startup.sh > logs/console.out 2>&1&
   [1] 32548

1. Download MySQL Connector/J, version 5.1 or later from the MySQL website. Unpack the delivery, and copy the .jar into the salesforceIdConnect/bundle directory.

   $ cp mysql-connector-java-version-bin.jar /path/to/salesforceIdConnect/bundle/

2. Remove the default OrientDB configuration file (/path/to/salesforceIdConnect/conf/repo.orientdb.json) from the configuration.

   $ cd /path/to/salesforceIdConnect/conf/
   $ rm repo.orientdb.json

3. Copy the MySQL JDBC configuration file (/path/to/salesforceIdConnect/db/scripts/mysql/repo.jdbc-mysql.json) to the salesforceIdConnect/conf directory and rename it repo.jdbc.json.

   $ cd /path/to/salesforceIdConnect/conf
   $ cp ../db/scripts/mysql/repo.jdbc-mysql.json repo.jdbc.json

4. Import the data definition language script for Identity Connect into MySQL.

   $ cd /path/to/mysql
   $ ./bin/mysql -u root -p < \
     /path/to/salesforceIdConnect/db/scripts/mysql/openidm_SalesforceIdentityConnect-MySQL.sql
   Enter password:
   $  

   Enter the root user password for the MySQL server.

   This step creates a database named openidm for use as the internal repository, and a user openidm with password openidm who has all the required privileges to update the database.

   Load the openidm database and verify that you can display the default Identity Connect tables.

   $ cd /path/to/mysql
        $ ./bin/mysql -u root -p 
        Enter password:
        Welcome to the MySQL monitor.  Commands end with ; or \g.
        Your MySQL connection id is 18
        Server version: 5.5.19 MySQL Community Server (GPL)
        ...
        mysql> use openidm;
        Reading table information for completion of table and column names
        You can turn off this feature to get a quicker startup with -A
   
        Database changed
        mysql> show tables;
        +---------------------------+
        | Tables_in_openidm         |
        +---------------------------+
        | auditaccess               |
        | auditactivity             |
        | auditrecon                |
        | clusterobjectproperties   |
        | clusterobjects            |
        | configobjectproperties    |
        | configobjects             |
        | genericobjectproperties   |
        | genericobjects            |
        | internaluser              |
        | links                     |
        | managedobjectproperties   |
        | managedobjects            |
        | objecttypes               |
        | orphanarium               |
        | orphanariumproperties     |
        | schedulerobjectproperties |
        | schedulerobjects          |
        | uinotification            |
        +---------------------------+
        19 rows in set (0.00 sec)

   The table names are similar to those used with the embedded OrientDB repository.

5. Update salesforceIdConnect/conf/repo.jdbc.json as necessary, to reflect the details of your MySQL deployment.

        "connection" : {
        "dbType" : "MYSQL",
        "jndiName" : "",
        "driverClass" : "com.mysql.jdbc.Driver",
        "jdbcUrl" : "jdbc:mysql://localhost:3306/openidm?characterEncoding=utf8",
        "username" : "openidm",
        "password" : "openidm",
        "defaultCatalog" : "openidm",
        "maxBatchSize" : 100,
        "maxTxRetry" : 5,
        "enableConnectionPool" : true,
        "connectionTimeoutInMs" : 30000
        },

   Specifically, make sure that the username and password used to access the database are correct, and that the jdbcUrl reflects the location of the database. The MySQL database can be either local (that is, running on the same host as the Identity Connect instance) or remote (running on a different host to the Identity Connect instance). If the database is on a remote host, adjust the jdbcUrl property accordingly, for example "jdbcUrl" : "jdbc:mysql://remoteMySQLServer.domain.com:3306/openidm?characterEncoding=utf8".

6. For optimum performance, tune the MySQL database to work effectively with Identity Connect. The following tuning steps are recommended:

   • Ensure that at least 4GBytes of memory is available to the MySQL instance.

   • Set the innodb_buffer_pool_size variable to at least 2GBytes. The value of this variable will depend on the amount of memory that is available to the MySQL instance. As a rule of thumb, the buffer pool size should be approximately 70%-80% of the memory available to the MySQL instance. For more information about this variable, see the corresponding MySQL documentation.

   • Set the innodb_file_per_table variable to ON. For more information about this variable, see the corresponding MySQL documentation.

   • On UNIX-like systems only, set the innodb_flush_method variable to O_DIRECT. For more information about this variable, see the corresponding MySQL documentation.

   • Start the Event Scheduler by setting the event_scheduler variable to ON. For more information about this variable, see the corresponding MySQL documentation.

     Caution

     Enabling the Event Scheduler is required. If you do not enable the Event Scheduler, the maintenance process that is used to keep the size of the log data to a minimum cannot run.

   • Set the transaction isolation level to READ-COMMITTED. For more information about setting the transaction isolation level, see the corresponding MySQL documentation.

1. Use SQL Management Studio to import the data definition language script for Identity Connect into MS SQL.

   1. Navigate to SQL Server Management Studio.

   2. On the Connect to Server panel, select Windows Authentication and click Connect.

   3. Select File > Open > File and navigate to the Identity Connect data definition language script (path\to\salesforceIdConnect\db\scripts\mssql\openidm_SalesforceIdentityConnect-MSSQL.sql). Click Open to open the file.

   4. Click Execute to run the script.

2. This step creates an openidm database for use as the internal repository, and a user openidm with password Passw0rd who has all the required privileges to update the database. You might need to refresh the view in SQL Server Management Studio to see the openidm database in the Object Explorer.

   Expand Databases > openidm > Tables. You should see the following tables in the openidm database:

   

   The table names are similar to those used with an OrientDB repository.

   Caution

   In a production environment, you should change the username and password for the user that access the openidm database. To do so, update the openidm_SalesforceIdentityConnect-MSSQL.sql script, editing the following line:

   IF (NOT EXISTS (select loginname from master.dbo.syslogins where
       name = N'your=new-name' and dbname = N'openidm'))
   CREATE LOGIN [openidm] WITH PASSWORD=N'your-new-password',
       DEFAULT_DATABASE=[openidm], CHECK_EXPIRATION=OFF, CHECK_POLICY=OFF
   GO  

   Update the repository configuration file (conf/repo.jdbc.json) to match these details, as described in Step 6.

3. Identity Connect requires an MS SQL driver that must be created from two separate jar files. Create the driver as follows.

   1. Download the Microsoft JDBC Driver for SQL Server that corresponds to your JVM version from Microsoft's download site. The precise URL might vary, depending on your location.

      For Java 8, you can use either version 4.1 or 4.2 of the JDBC Driver.

      Extract the executable Java archive file (sqljdbc41.jar or sqljdbc42.jar) from the zip file, using 7-zip or an equivalent file management application.

      Copy the JAR file to salesforceIdConnect\db\scripts\mssql.

      The remaining steps assume that you have downloaded the 4.1 version of the driver. If you are using version 4.2 of the driver, adjust the instructions accordingly.

   2. Download the bnd Java archive file (bnd-1.50.0.jar) that enables you to create OSGi bundles. For more information about bnd, see http://bnd.bndtools.org/.

      Copy the file to salesforceIdConnect\db\scripts\mssql.

   3. Your salesforceIdConnect\db\scripts\mssql directory should now contain the following files:

      PS C:\> ls .\salesforceIdConnect\db\scripts\mssql
         
      Directory: C:\salesforceIdConnect\db\scripts\mssql
      
      Mode                LastWriteTime     Length Name
      ----                -------------     ------ ----
      -a---         7/22/2015   4:18 AM     828249 bnd-1.50.0.jar
      -a---         7/21/2015   6:39 AM      21131 openidm_SalesforceIdentityConnect-MSSQL.sql
      -a---         7/21/2015   6:39 AM      19568 repo.jdbc-mssql.json
      -a---         7/21/2015   6:39 AM        642 sqljdbc4.bnd
      -a---         12/9/2014   2:17 PM     586192 sqljdbc41.jar

   4. Change to the salesforceIdConnect\db\scripts\mssql directory, and bundle the two jar files together with the following command:

      PS C:\salesforceIdConnect\db\scripts\mssql> java -jar bnd-1.50.0.jar ^
          wrap -properties sqljdbc4.bnd sqljdbc41.jar
      sqljdbc41  236  0   

      Note

      This command assumes that you have set the JAVA_HOME environment variable to point to a valid JRE installation directory.

      This step creates a single .bar file, named sqljdbc41.bar.

   5. Rename the sqljdbc41.bar file to sqljdbc41-osgi.jar and copy it to the salesforceIdConnect\bundle directory.

      PS C:\salesforceIdConnect\db\scripts\mssql> mv sqljdbc41.bar sqljdbc41-osgi.jar
      PS C:\salesforceIdConnect\db\scripts\mssql> cp sqljdbc41-osgi.jar ..\..\..\bundle

4. Remove the default OrientDB repository configuration file (salesforceIdConnect\conf\repo.orientdb.json) from the configuration directory.

   PS C:\> cd salesforceIdConnect\conf
   PS C:\> rm repo.orientdb.json

5. Copy the MS SQL JDBC configuration file (salesforceIdConnect/db/scripts/mssql/repo.jdbc-mssql.json) to the salesforceIdConnect/conf directory and rename it repo.jdbc.json.

   PS C:\> cd salesforceIdConnect\db\scripts\mssql
   .\> cp repo.jdbc-mssql.json ..\..\..\conf\repo.jdbc.json

6. Update the repository configuration file (repo.jdbc.json as necessary, to reflect your MS SQL deployment.

   {
       "connection" : {
           "dbType" : "SQLSERVER",
           "jndiName" : "",
           "driverClass" : "com.microsoft.sqlserver.jdbc.SQLServerDriver",
           "jdbcUrl" : "jdbc:sqlserver://localhost:1433;instanceName=default;
                        databaseName=openidm;applicationName=OpenIDM",
           "username" : "openidm",
           "password" : "Passw0rd",
           "defaultCatalog" : "openidm",
           "maxBatchSize" : 100,
           "maxTxRetry" : 5,
           "enableConnectionPool" : true
       },
   ...

   Specifically, check that the port matches what you have configured for MS SQL.

1. On each host that will contain an Identity Connect instance, unpack the contents of the .zip file into the install location, but do not set up Identity Connect.

2. Configure each Identity Connect instance for a remote MySQL database, as described in Chapter 11, "Installing an Alternative Repository".

   Note that you only need to import the data definition language script (Step 4 of this procedure) for the primary Identity Connect instance. Additional instances will read the database from the primary instance.

   When you edit the /path/to/salesforceIdConnect/conf/repo.jdbc.json file (Step 5 of this procedure), set the "jdbcUrl" property to point to the remote MySQL server. For example:

   "jdbcUrl" : "jdbc:mysql://server-ip:3306/openidm?characterEncoding=utf8"

   where server-ip is the IP address of the server on which the MySQL server is located.

3. On each Identity Connect instance, edit the conf/boot/boot.properties file, as follows:

   1. Specify a unique identifier for the instance.

      For example, on the primary instance:

      $ grep openidm.node.id /path/to/salesforceIdConnect/conf/boot/boot.properties
      openidm.node.id=IdentityConnect1

      On subsequent instances, the openidm.node.id can be set to IdentityConnect2, IdentityConnect3, and so forth. You can choose any value, as long as they are unique.

   2. Specify the instance type in the cluster.

      On the primary instance, add the following line to the boot.properties file:

      openidm.instance.type=clustered-first

      On subsequent instances, add the following line to the boot.properties file:

      openidm.instance.type=clustered-additional

4. On all instances except the primary instance, edit the conf/system.properties file, to prevent Identity Connect from reading its configuration from the configuration files, by uncommenting the line openidm.fileinstall.enabled=false.

   This forces Identity Connect to read its configuration only from the repository, in this case, the repository of the primary instance.

   $ grep openidm.fileinstall /path/to/salesforceIdConnect/conf/system.properties
   openidm.fileinstall.enabled=false

5. Start up the primary Identity Connect instance and configure it.

   Make sure that when you initially access this Identity Connect instance, you use the FQDN (https://host.domain:8443/admin) and not localhost.

6. If you imported a certificate for Active Directory during the Identity Connect setup, or if you have modified the truststore on the primary instance, copy the truststore file from the primary instance to the secondary (and additional) instances. For example, run the following command on the primary instance, substituting the hostname or IP address of each secondary instance:

   $ cd /path/to/salesforceIdConnect
   $ scp security/truststore admin@host2.example.com:/home/testuser/salesforceIdConnect/security/

7. Make sure that the secondary instance (and any additional instances) have access to the MySQL database on the primary instance.

   You can check that the secondary instance has access by running a command similar to the following:

   mysql -u openidm -p -h primary.instance.host.name openidm

   If your secondary instance cannot access the primary database, you might need to set the appropriate privileges. For example:

   GRANT ALL PRIVILEGES ON openidm.* to 'openidm'@'primary.instance.host.name' IDENTIFIED BY 'openidm';

   To identify the privileges required on the MySQL server, run the following command:

   select user,host from mysql.user;

   This command displays the user and the related host, and all the privileges that are granted to that user.

8. Start up the secondary (and additional) instances.

   Additional instances read the configuration from the first instance, so requests to https://host2.example.com:8443/connect should read the existing Identity Connect configuration from the first host.

1. Stop Identity Connect, if it is running.

   • To stop Identity Connect on UNIX-like systems, run the shutdown script, located in the install directory.

     $ cd /path/to/salesforceIdConnect
     $ ./shutdown.sh
     Stopping OpenIDM (91957)

   • To stop Identity Connect on Windows systems, stop the OpenIDM application in the Windows Task Manager, or type shutdown in the Felix console that opened when you started Identity Connect.

2. Delete and recreate the repository schema.

   • For an OrientDB repository, delete the db/openidm directory and all its subdirectories.

   • For an external JDBC repository, drop the openidm schema and re-create it, as described in Section 11.1, "Setting Up Identity Connect With MySQL".

3. Restart Identity Connect.

   • To restart Identity Connect on UNIX-like systems, run the startup script, located in the install directory.

     $ cd /path/to/salesforceIdConnect
     $ ./startup.sh

   • To restart Identity Connect on Windows systems, run the startup.bat script in the installation directory.

4. Log in to the administrative interface (https://hostname.domain:8443/admin/).

5. Select the Salesforce.Org tab.

6. For each configured Salesforce organization, select the Mapping tab, and perform the following tasks.

   1. Select Permission Set to AD Group and recreate any previously defined permission set to group mappings.

      Click Update Now to refresh any cached data.

   2. Select SF Group to AD Group and recreate any previously defined group mappings.

      Click Update Now to refresh any cached data.

7. Select the Sync tab.

   Add any users who had previously been marked as ignored to the list of Ignored Users.

8. Click Sync Now to perform a reconciliation. Depending on the size of the database and system hardware, this process might take a number of minutes.