Synchronize your company directory with LDAP directories

Agent tools Edit article Translate article Show labels

This article allows to synchronize the company directory in Rainbow with the LDAP directories located in company premises. Synchronization is unidirectional (one-way) from LDAP directory to Rainbow.

After synchronization is successful:

• Company members in LDAP directory are automatically created in Rainbow with a company subscription (i.e. the Rainbow license assigned to new members in company).
  Company member creation fails when there are no more Rainbow licenses available for the company.

• Company member settings for which an LDAP/Rainbow mapping has been defined are automatically updated in Rainbow.

  Note: The company member e-mail cannot be updated from LDAP directory to Rainbow.
• Company members deleted in LDAP directory are automatically set to 'pending deletion' in Rainbow, and permanently deleted after a grace period (i.e. 10 days). During this period, the deletion of company members can be cancelled from the Members panel of Rainbow administration interface.
• Optionally (if configured in Rainbow), contacts in LDAP directory are automatically created in Rainbow.

Synchronization is performed by the Rainbow LDAP Connector connected to LDAP directory.

The Rainbow LDAP Connector supports synchronization with multiple LDAP directories or LDAP directories with multiple domains.

Before you start

• The Rainbow LDAP Connector must be installed on a computer and associated to the company: see article Run the Rainbow LDAP Connector as a Windows service.
• You must have an administrator account in the company with a Business or Enterprise license.

• You must have subscribed enough Business and/or Enterprise licenses to create/update all expected users at synchronization.

  Warning: If there are not enough licenses, you will see the following error message in the synchronization report "No default licence managed or no available default licences to create/update user ".

Configuration overview

The Rainbow LDAP Connector configuration in company premises consists in:

1. From the Rainbow application and company management menu, modifying the LDAP directory users and/or contacts to be synchronized
2. Optionally, modifying the predefined attribute mapping between LDAP directory and Rainbow

3. Verifying configuration (dry run process), and launching a manual synchronization with LDAP directory

   Note: Manual synchronization is only available after successful dry run.
4. Configuring a periodic synchronization with LDAP directory
5. Enabling/disabling enrollment email to new users created in Rainbow

The scheduled and manual synchronizations automatically generate reports available for download: see Monitoring synchronization reports from Rainbow.

Accessing the management window

1. From the Rainbow administration interface, click on Manage your company in the left panel.
2. In the MY COMPANY panel, click on the company name, then Members.
3. Click on Import.
4. Click on icon .
   The Rainbow LDAP Connector management page opens.

Connection information with Rainbow LDAP Connector are displayed at the top of the window. Status is Running when Rainbow LDAP Connector is connected to LDAP directory.

Example:

Available actions are:

• To refresh connection status: click on icon in the Status column.
• To generate activity report: click on icon to the right of the Status column. The reports are available in the Reports panel of Rainbow administration interface.
• To remove connection: click on icon to the right of the Status column. This allows to connect and register a new Rainbow LDAP Connector to Rainbow (e.g. after a host computer change).
• When the company has multiple LDAP directories/domains:
  • To modify the LDAP directory/domain name: click on icon to the right of the name
  • To switch from an LDAP directory/domain to another one: click on icon to the right of the name
  • To configure synchronization to a new LDAP directory/domain: click on icon to the right of the name

Modifying the LDAP directory objects to be synchronized

The selected objects can be LDAP directory users and/or contacts.

When the company has multiple LDAP directories/domains, these operations must be performed for each LDAP directory or domain.

The option Remove this configuration deletes user synchronization in this LDAP directory/domain but will preserve directory synchronization, if it exists.

Modifying the users to be synchronized

1. From the Rainbow LDAP Connector management window, in the Users Selector section, select the LDAP directory users to be synchronized:
   • Base DN: enter the root domain where the Active Directory users are located (use LDAP syntax).
   • Filter: optionally, apply a filter to synchronize only a subset of LDAP directory users (use LDAP syntax for filter definition). By default, all users in LDAP directory (person objects) are synchronized.
2. Select Users deletion enabled to enable the users deleted in LDAP directory to be also deleted in Rainbow.
3. Select Delete missing LDAP records if any previously found LDAP directory users, which are no more found after new search, must be considered as 'to be deleted'. If Delete missing LDAP records is unselected, only records found with a new search using Base DN for deletion and Filter for deletion will be considered as "to be deleted" in Rainbow.
4. In the Base DN for deletion field, enter the location on LDAP directory where the deleted LDAP directory users have been moved (use LDAP syntax).
5. Optionally, in the Filter for deletion field, apply a filter to select only a subset of LDAP directory users (use LDAP syntax for filter definition).
6. Click on Update.

Modifying the contacts to be synchronized

1. From the Rainbow LDAP Connector management window, in the Business Directory Selector section, select the LDAP directory contacts to be synchronized:
   • Base DN: enter the root domain where the Active Directory contacts are located (use LDAP syntax).
   • Filter: optionally, apply a filter to synchronize only a subset of LDAP directory contacts (use LDAP syntax for filter definition). By default, all contacts in LDAP directory (contact objects) are synchronized.
2. Click on Update.

Configuring LDAP/Rainbow attribute mapping

Attribute mapping defines the correspondence between the attributes of LDAP directory and the attributes of Rainbow. Two different mapping tables must be configured for users and contacts.

Attribute mapping for users

To configure the attribute mapping table for users:

1. From the Rainbow LDAP Connector management window, in the Users Selector section, click on Define Attribute Mapping.
   The default mapping table is:
   

2. For each Rainbow attribute to be mapped, enter the corresponding Active Directory attribute in the LDAP Attribute column.

   User attribute	LDAP attribute
   loginEmail	This attribute is mandatory and typically set to userPrincipalName or mail
   ldap_id	This attribute is mandatory and typically set to objectGUID or sAMAccountName. Ldap_ID is a hidden field allowing to identify that users have been created by AD connector. It must contain a unique ID from LDAP directory always allocated to the same user
   firstname	This attribute is mandatory and typically set to givenName
   lastName	This attribute is mandatory and typically set to sn
   pbxInternalNumber pbxShortNumber number	When the company is associated to a PBX equipment, and LDAP directory includes PBX telephone settings, these optional attributes can be configured to retrieve PBX telephone settings: pbxInternalNumber to retrieve the phone set numbers pbxShortNumber to retrieve internal numbers number to retrieve the public numbers
   pbxLdapId attribute	When the company has multiple PBX equipment, and some PBXs have the same internal number, add this attribute in the User Attribute column and enter SiteName in the LDAP Attribute column. For each target PBX, go to: Communication > [PBX] > Information, and in the Equipment LDAP name field, enter the name of the site hosting the PBX.
   country language timezone	These optional attributes can be set to constant values. Syntax is Const("x") where x is: A three-letter code for country (e.g. Const("ARG") for Argentina) A two-letter code (ISO 639-1) for language (e.g. Const("de") for German) An area/location string for time-zone (e.g. Const("Europe/Paris"))
   tags0 to tags4 userinfo1 and userinfo2	These optional attributes can be set to constant values. Syntax is Const("x") where x is the constant value (e.g. Const("sales"))
   department	This attribute is optional and typically set to department
   nickname	This optional attribute is used to add nicknames to users
   Avatar	This optional attribute is used to download photos that will be used as user avatars. It must be set to any value (e.g. True). The photo synchronization is done after user synchronization. Photos are downloaded one by one and are not included in the CSV file.
   AuthenticationExternalUid	These attributes are used when SSO authentication is used for Rainbow and Rainbow login differs from SSO login. For example, Rainbow users authenticate with user@xxx.com, while on Microsoft SSO, they use user@xxx.msft.com.
   AuthenticationType
   selecedtAppCustomisationTemplateName	This optional attribute must contain the name of a custo-manifest.json file configured in Rainbow for company members.
   selectedProgKeysGroupName	This optional attribute must contain the name of a group of programmable keys configured in Rainbow for company members.
   isActive	This optional attribute is used to configure the user activation state (active or inactive)
   rainbowPasswordlessPolicySendToEmail	When a Rainbow passwordless authentication method is assigned to users, this optional attribute is used to specify the email address on which users will receive the access code (default is their loginEmail)
   macAddress (*)	This optional attribute is used to associate the SIP device mac address to users
   customSipHeader_1 (*)	This optional attribute is used to define the first custom SIP header
   customSIPHeader_2 (*)	This optional attribute is used to define the second custom SIP header

   (*): These user attributes only apply to companies associated to Cloud PBX.

3. Click on Apply to validate changes and close the mapping table.
4. Click on Update.

SPECIAL CASE: an attribute mapping cannot be configured because there is no corresponding attribute in Active Directory. In this case, the Active Directory attribute can be replaced by an associated value found in a table inserted in LDAP attribute. Syntax is:

 "ldapFieldName::REPLACE({"default": "value0", "table": [ { "LdapValue1": "value1" }, ... { "LdapValueN": "valueN" } ] }) 

Example: the Active Directory does not contain a language attribute as required but only a country attribute. In this case, language mapping can be based on country as follows: 

"country::REPLACE({"default": "en", "table": [ { "France": "fr" }, { "Spain": "es" } ] }) 

In this example, Rainbow LDAP Connector searches for country attribute in Active Directory. If result is 'France', LDAP attribute will be set to 'fr', if result is "Spain", it will be set to 'es', and so on, and if there is no result, it will be set to 'en'.

Attribute mapping for contacts

To configure the attribute mapping table for contacts:

1. From the Rainbow LDAP Connector management window, in the Business Directory Selector section, click on Define Attribute Mapping.
   The default mapping table is:
   
2. For each Rainbow attribute to be mapped, enter the corresponding LDAP directory attribute in the LDAP Attribute column.
3. Click on Apply to validate changes and close the mapping table.
4. Click on Update.

Verifying configuration and launching a manual synchronization with LDAP directory

From the Rainbow LDAP Connector management window, in the Users Selector section (or Business Directory Selector section for contacts), click on Dry run.

A user or contact import simulation in Rainbow is performed, and a report is displayed indicating how many users or contacts will be added/modified, detached (for users only), or deleted.

If the result is correct, you can launch a manual synchronization: select Do you want to start the import process?, click on Synchronize, and confirm by clicking on Synchronize again.

Configuring a periodic synchronization with LDAP directory

Periodic synchronization can be enabled or disabled for LDAP directory users only, or for contacts only.

To program a periodic synchronization:

1. From the Rainbow LDAP Connector management window, in the Users Selector section (or Business Directory Selector section for contacts), select Automatic users synchronization enabled.
2. At the top of the management window, in the Synchronization period (hour) field, enter the interval time (in hours) between two synchronizations.
3. In the Next synchronization field, enter the date and time of the next synchronization.
4. In case of large organization, in the Users Selector section, select Differential synchronization mode to reduce the response size of LDAP query. When selected, at next synchronization, LDAP query only requests the users created or modified since the last synchronization.
5. Click on Update.

To interrupt a periodic synchronization, from the Rainbow LDAP Connector management window, in the Users Selector section (or Business Directory Selector section for contacts), unselect Automatic users synchronization enabled.

Enabling/disabling enrollment email to new users

1. From the Rainbow LDAP Connector management window, in the Users Selector section, select or unselect Send enrollment email to new users.
   If enabled, new users are notified by email they have a user account in Rainbow.
2. Click on Update.

Monitoring synchronization reports from Rainbow

The report of the last synchronization is directly available in the Rainbow LDAP Connector management window.

Click on the report to display all the synchronization tasks (users/contacts created, updated and deleted) and their status (success, warning, failure).

Available actions are:

• To download the report, click on Save Reports, and download it in Excel format.
• To delete the report, click on icon to the right of the report.
• To access all the previous reports, click on Sync reports tab at the top of the window.
  In Done by column, ldap connector indicates the report concerns an LDAP directory synchronization.
  In Description column, manual_synchro indicates a manual synchronization and auto-interval a scheduled synchronization.

Monitoring the Rainbow LDAP Connector running status

1. From the computer, access the installation folder of Rainbow LDAP Connector and double click on rainbow-ad-page file.
   This opens a login page in a web navigator.
2. Log in with your company administrator credentials and validate.
   The Rainbow LDAP Connector window opens.

The status window displays:

• The Rainbow LDAP Connector software version
• The associated Rainbow company name
• The connection status to Rainbow Cloud
• The connection status to LDAP directories
• A link to access Log files
• The last synchronization date/time
• The last synchronization digest report (LDAP response records/selected records)