Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

LabKey Server can be configured to automatically synchronize with an external LDAP server, so that any user and groups found on the LDAP server are duplicated on LabKey Server. This synchronization is one way: any changes made within LabKey will not be pushed back to the LDAP server.

There are several options to control the synchronization behavior, including:
  • Specifying a synchronization schedule
  • Whether or not LabKey Server creates a user account corresponding to an LDAP user
  • Whether or not LabKey Server creates groups corresponding to LDAP groups
  • Deactivating a LabKey account for users with inactive LDAP accounts
  • Synchronizing based on user and group filters
  • Field mapping between the LDAP and LabKey user information
  • Choosing to enforce or disallow the overwriting of user account information in LabKey
Syncing nested groups is not supported. Groups that are members of other groups must be manually configured in LabKey.

Tomcat Configuration

Note that LDAP synchronization is independent of LDAP authentication and requires a separate connection resource added to the labkey.xml file, described below.

To set up an LDAP synchronization connection:

  • Add a <Resource> to the Tomcat configuration file (labkey.xml).
  • See the example configuration below for a starting template. Replace ADMIN, ADMIN_PASSWORD, and MYLDAP.MYDOMAIN.COM with values appropriate to your organizations LDAP server.
<Resource name="ldap/ConfigFactory" auth="Container"

For details see Installation: SMTP, Encryption, LDAP, and File Roots.

LDAP Sync Settings

Once the LDAP resource has been added, configure the synchronization behavior as follows:

  • Go to (Admin) > Site > Admin Console.
  • Under Premium Features, click LDAP Sync Admin.
The page contains several sections of settings, detailed below.

Connection Settings

To test a connection with an LDAP server, click the Test Connection button.

Search Strings

Use the Search Strings section to control which groups and users are queried on the LDAP server. These settings are optional. Use LDAP syntax to specify search parameters such as "dc=edu" to retrieve .edu addresses.

  • Base Search String
  • Group Search String
  • Group Filter String
  • User Search String
  • User Filter String
An example Group Search string:


You can also control which groups to synchronize using the graphical user interface described below. The string settings made here override any groups chosen in the graphical user interface.

Field Mapping

Use Field Mappings to control how LabKey Server fields are populated with user data. The fields on the left refer to LabKey Server fields in the core.Users table. The fields on the right refer to fields in the LDAP server.

  • Email
  • Display Name
  • First Name
  • Last Name
  • Phone Number
  • UID

Sync Behavior

This section configures how LabKey Server responds to data retrieved from the synchronization.

  • Read userAccountControl attribute to determine if active?: If Yes, then LabKey Server will activate/deactivate users depending on the userAccountControl attribute found in the LDAP server.
  • When a User is Deleted from LDAP: LabKey Server can either deactivate the corresponding user, or delete the user.
  • When a Group is Deleted from LDAP: LabKey Server can either delete the corresponding group, or take no action (the corresponding group remains on LabKey).
  • Group Membership Sync Method: Changes in the LDAP server can either overwrite account changes made in LabKey, or account changes in LabKey can be respected by the sync.
    • Keep in sync with LDAP changes
    • Keep LabKey changes (this allows non-LDAP users to be added to groups within LabKey)
    • Do nothing
  • Set the LabKey user's information, based on LDAP? - If Yes, then overwrite any changes made in LabKey with the email, name, etc. as entered in LDAP.

Choose What to Sync

Choices made here are overwritten by any String Settings you make above.

  • All Users (subject to filter strings above): Sync all users found on the LDAP system.
  • All Users and Groups (subject to filter strings above): Sync all users and groups found on the LDAP system.
  • Sync Only Specific Groups and Their Members: When you select this option, available LDAP groups will be listed on the left. To sync a specific group, copy the group to the right side. Click Reset Group List to clear the selected groups panel.


  • Is Enabled? If enabled, the schedule specified will run. If not enabled, you must sync manually using the Sync Now button below.
  • Sync Frequency (Hours): Specify the cadence of sync refreshes in hours.

Save and Sync Options

  • Save All Settings on Page: Click this button to confirm any changes to the sync behavior.
  • Preview Sync: Provides a popup window showing the results of synchronization. This is a preview only and does not actually make changes on LabKey Server.
  • Sync Now: Perform a manual, unscheduled sync.

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all