Installing an LDAP Directory Connector

1. Go to Users > Directories and add a New Directory. Choose LDAP via Connector, enter a name for the directory in the title field, and Save the directory to enable additional configuration options.

   

2. A single LDC instance is created by default. You may later choose to Add LDAP Connector Instance if configuring multiple LDAP connectors for high availability, but for now, select your first connector instance to view its details.

   

   1. Enter a descriptive Name for the connector.
   2. Enter your LDAP domain controller's Hostname or IP address.
   3. Enter a Port for the domain controller (DC).
   4. Copy the Installation Token for use during the installation.
   5. Download the LDC installation file.

   

3. Extract and install the LDC to your desired host machine according to the steps provided in the included README file and edit its configuration file to add the installation token copied from OneLogin.

   Only the installation token is required. All other configuration settings are optional. They may be configured now, or disregarded for a default installation.

4. Start the LDC using start-ldc.bat (Windows) or start-ldc.sh (Linux/Unix/OS X).

5. Return to the new directory in your OneLogin admin portal and refresh the page. If the LDC has succesfully connected to your OneLogin account and started running, its connector instance now displays ● Connected and additional configuration pages appear in the left sidebar.

6. Go to Connection and enter the additional connection details required for OneLogin to connect to your LDAP server:

   Bind DN	The admin DN you use to connect to your LDAP server
   Password	The password you use to identify the admin Bind DN
   Authentication attribute	The LDAP attribute that your users will enter as their username on OneLogin's login page
   UUID Attribute	The LDAP attribute that you use to uniquely identify your users
   Base DN	The LDAP attribute that is used as the root context DN of your LDAP directory

   Important: The fields used as your authentication and UUID attributes must be indexed in your LDAP server in order to prevent issues with authenticating users through the connector. See your server provider's documentation for more information.

7. Go to OU Selection to select the organizational units (OUs) you want to import to OneLogin.

   Note: It may take several seconds to retrieve your directory's OU tree. If the tree does not appear, wait two minutes and refresh the page.

8. Save your changes; the directory connector is now configured to sync your selected OUs with OneLogin according to the default configuration. Go to More Actions > Synchronize to begin your first import, or install additional connectors for failover availability.

Configuring an LDAP Directory Connector

Directory Mappings

By default, OneLogin maps several directory attributes to be imported when users are synced with your LDAP directory. If preferred, you can add to or modify these default mappings.

Adding Custom Mappings

If you'd like to map a custom user field in OneLogin to your LDAP directory, click + to add a new row to your mappings and select the appropriate attributes from the dropdown menus provided.

Modifying Sync Directions

By default, all directory mappings are inbound from your LDAP directory, meaning that the directory owns all field values and sends these to override the corresponding values in OneLogin. If you have Exporting users enabled in your advanced LDC settings, you can select the arrows in the Import/Export column to change some or all of your user fields to an outbound mapping, allowing OneLogin to provision these attributes to the LDAP directory instead.

Note: If you wish to enable LDAP user deletion in your configuration file, all attributes must be configured for outbound mapping.

Advanced Settings

Go to Advanced to manage additional features and settings:

Installation Files

The installation contains two configuration files:

• conf/ldc-default.conf — The factory default configuration settings. Do not edit this file.
• conf/ldc.conf — The site-specific configuration. This file may be edited with your preferred settings.

When the LDC is started, it first loads the conf/ldc-default.conf configuration, then overrides these settings with any located in conf/ldc.conf. By default, the conf/ldc.conf file contains only the most commonly customized settings, but you can customize additional settings by copying them in from conf/ldc-default.conf.

Secure Properties

Some configuration properties, like passwords, must be secured in your configuration file. These can be encrypted by using the secure-properties utility.

1. Add the SECURE_PASSWORD environment variable to your conf/ldc.conf file with the password to be used for encrypting and decrypting properties.

   E.g., SECURE_PASSWORD=ABC(1DefGHiJk2lm3NOp4QrSTU5vW6XYZabcDEfGHI7jK8l=).

2. Run the script ./bin/secure-properties.sh (Linux/Unix/OS X) or .\bin\secure-properties.bat (Windows).

3. Introduce the value to be encrypted.

4. Copy the encrypted value to the configuration property that requires additional security.

Starting and Stopping an LDAP Directory Connector

Best Practice: We recommend enabling Directory Fallback Password Cache in your account settings to prevent an outage in the event that all connectors experience disconnection, as well as configuring multiple LDC instances for failover purposes and enabling automatic failover in your directory's Advanced settings.

To monitor the status of any directories you have configured, go to Users > Directories in your OneLogin admin portal and select the directory to view details about its connectors. Any failed LDC instances will display a ⬤ Disconnected indicator.

Starting the Connector

The connector can be started as either a foreground or a background process, depending on your needs. When you first configure the LDC, you may wish to start it in the foreground in order to see errors and enable fast stopping. Once you've completed deployment and testing, you may change it to a background process to allow it to continue running as necessary.

In Windows, edit the text file start-ldc.bat in the bat folder, or in Linux/Unix/OS X, edit start-ldc.sh in the bin folder. In this file, set the environment variable BACKGROUND to either "true" or "false". When the script is run in the foreground, console messages will be displayed in the command window. When run in the background, they will be directed to .\logs\ldc_console.log.

Tuning Starting Performance

Stopping the Connector

If necessary, it is possible to hard-stop the connector by killing the Java Process ID in Linux/Unix/Mac OS X, or by ending the Java process in the Windows Task Manager. However, we recommend stopping the connector gracefully whenever possible so that it is able to notify OneLogin cloud services of associated connection, monitoring state, and failover state updates. This can be done with the commands $ ./bin/stop-ldc.sh (Linux/Unix/Mac OS X) or > .\bin\stop-ldc.bat (Windows).

Upgrading an LDAP Directory Connector

1. Gracefully stop the existing installation and copy its conf/ldc.conf configuration file to a secure location. Uninstall the previous connector.

2. In your OneLogin admin portal, open the LDC instance and verify that its Installation Token matches that stored in your configuration file. Download the new installation file.

3. Extract and install the new installation as normal, and replace its conf/ldc.conf with your previous configuration file to restore your installation token and any other customized settings.

Tip: If you have multiple connectors installed for high availability, we recommend upgrading the standby connectors first, then promoting an upgraded standby connector to Active before upgrading the previously Active connector.

Monitoring an LDAP Directory Connector

The LDAP Directory Connector version 2.0 and above uses the Simple Logging Facade for Java (SLF4j). This framework uses an XML-formatted configuration file that you can edit to do the following:

• Set the directory path and filename to the connector log file
• Set the format of logged messages
• Set the threshold (DEBUG, INFO, WARN, ERROR) of logged messages
• Set the log file rollover triggering policy (size, date, etc.)
• Set the log file rollover naming policy
• Set the maximum number of rolled over log files to keep

The LDAP Directory Connector is distributed with a default logging configuration file (embedded within the onelogin-ldc.jar file) that displays INFO, ERROR, and WARN messages, but omits more detailed DEBUG-level messages. It uses the following message format:

[2016-10-11 16:32:23,246] [ldc-main] INFO  - Starting: OneLogin LDAP Directory Connector
[2016-10-11 16:32:23,246] [ldc-main] INFO  - Version: 2.3.8
[2016-10-11 16:32:23,246] [ldc-main] INFO  - Release Date: September 17, 2016 7:01:00 PM
[2016-10-11 16:32:23,247] [ldc-main] INFO  - CONNECTOR: Started

The fields logged by default include:

• Date/time stamp
• Name of the java thread from which the log message was issued
• Message level (e.g. INFO)
• Context-sensitive message

The LDAP Directory Connector distribution also includes an additional logging configuration file, ./conf/logback-debug.xml, which is preconfigured for DEBUG-level logging.

You can edit this config file as needed (or use it as a template to create your own) and reference it directly from the command line when you launch the LDAP Directory Connector, using the command-line option -Dlogback.configurationFile=./logback-debug.xml before the -jar command, like this:

$ java -Xms1g -Xmx2g -XX:+UseG1GC -XX:MaxGCPauseMillis=500 -Dlogback.configurationFile=./logback-debug.xml -jar onelogin-ldc.jar -f <config-file-path>

The default logging configuration rotates the file when it reaches 100MB. It looks like this: 

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
	
  <appender name="commonlogfile" class="ch.qos.logback.core.rolling.RollingFileAppender">
		<!--See also http://logback.qos.ch/manual/appenders.html#RollingFileAppender-->
		<File>logs/ldap_connector.log</File>
		<encoder>
			<pattern>[%d{ISO8601}] |%t| %-5p - %m%n</pattern>
		</encoder>
		<filter class="ch.qos.logback.classic.filter.ThresholdFilter">
			<level>INFO</level>
		</filter>
		<rollingPolicy class="ch.qos.logback.core.rolling.FixedWindowRollingPolicy">
			<maxIndex>5</maxIndex>
			<FileNamePattern>logs/ldc.%i.log.zip</FileNamePattern>
		</rollingPolicy>
		<triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
			<MaxFileSize>100MB</MaxFileSize>
		</triggeringPolicy>
	</appender>
  
  
  <root level="DEBUG">
    <appender-ref ref="commonlogfile" />
  </root>
</configuration>