Premium Feature starting in version 20.3 (March 2020) — Available in the Professional, Professional Plus, and Enterprise Editions. Learn more or contact LabKey.

LabKey Server can use your organization's LDAP server to authenticate users. Using LDAP for authentication has a number of advantages: (1) you don't need to add individual users to LabKey and (2) users don't need to learn a new ID & password (they use their existing network id and password to log into your LabKey site). By default, if you set up a connection to your LDAP server, any user in the LDAP domain can log on to your LabKey application. You can change this default behavior by disabling auto-creating of user accounts. The permissions a user will have are the permissions given to "Logged in users" in each project or folder.

If you are not familiar with your organization's LDAP servers, you will want to recruit the assistance of your network administrator for help in determining the addresses of your LDAP servers and the proper configuration.

LDAP Authentication Process

When a user logs into LabKey with an email address ending in the LDAP domain:

  • LabKey attempts to connect to each LDAP server listed in LDAP Servers, in sequence starting with the first server provided in the list.
  • If a successful connection is made to an LDAP server, LabKey authenticates the user with the credentials provided. After a successful LDAP connection, no further connection attempts are made against the list of LDAP servers, whether or not the user's credentials are accepted or rejected.
  • If the user's credentials are accepted by the LDAP server, the user is logged on to the LabKey Server.
  • If the user's credentials are rejected by the LDAP server, then LabKey authenticates the user via database authentication (provided database authentication is enabled).
  • If the list of LDAP servers is exhausted with no successful connection having been made, then LabKey authenticates the user via database authentication (provided database authentication is enabled).
Note: When configuring LabKey to use an LDAP server you are trusting that the LDAP server is both secure and reliable.

Configure LDAP Authentication

To configure LDAP, follow these steps:

  • Select (Admin) > Site > Admin Console.
  • Click the Settings tab.
  • Under Configuration, click Authentication.
  • On the Authentication page, next to LDAP, click Configure.
    • To add a new CAS provider: Click Add > CAS ....
      • OR
    • To edit an existing provider: Click Edit next to the target provider.
  • On the Configure CAS Authentication page, enter the following fields:
  • Description: Enter a unique descriptive label for this provider.
  • LDAP Servers: Specifies the addresses of your organization's LDAP server or servers. You can provide a list of multiple servers separated by semicolons. The general form for the LDAP server address is ldap://, where 389 is the standard port for non-secured LDAP connections. The standard port for secure LDAP (LDAP over SSL) is 636. Note that if you are using secure SSL connections, Java needs to be configured to trust the SSL certificate, which may require adding certificates to the cacerts file. LabKey Server attempts to connect to these servers in the sequence provided here: for details see below.
  • LDAP Domain: For all users signing in with an email from this domain, LabKey will attempt authentication against the LDAP server, and for email accounts from other domains, no LDAP authentication is attempted. Set this to an email domain (e.g., ""), or use '*' to attempt LDAP authentication on all email addresses entered, regardless of domain.
    • Note: The LDAP Domain setting should match the "System default domain" set via (Admin) > Site > Admin Console > Settings > Site Settings. If the system default domain is unset, or contains a different value, authentication using only the username will not succeed.
  • LDAP Principal Template: Enter an LDAP principal template that matches the requirements of the configured LDAP server(s). The template supports substitution syntax: include ${email} to substitute the user's full email address and ${uid} to substitute the left part of the user's email address. The default value is ${email}, which is the format required by Microsoft Active Directory. Other LDAP servers require different authentication templates. For example, Sun Directory Server requires a more detailed principal template such as: uid=${uid},ou=people,dc=mydomain,dc=org. Check with your network administrator to learn more about your LDAP server.
Use SASL authentication: Check the box to use SASL authentication. You can use the Test LDAP Settings link on this page to test your LDAP authentication settings. See below.

LDAP Security Principal Template

The LDAP security principal template must be set based on the LDAP server's requirements. You can specify two properties in the string that LabKey will substitute before sending to the server:

PropertySubstitution Value
${email}Full email address entered on the login page, for example, ""
${uid}Left part (before the @ symbol) of email address entered on the login page, for example, "myname"

Here are a couple sample LDAP security principal templates that work on LDAP configurations we've tested with LabKey:

ServerSample Security Principal Template
Sun Directory Serveruid=${uid},ou=people,dc=cpas,dc=org
Microsoft Active Directory Server${email}

Note: Different LDAP servers and configurations have different credential requirements for user authentication. Consult the documentation for your LDAP implementation or your network administrator to determine how it authenticates users.

Testing the LDAP Configuration

  • From the LDAP Configuration page, click Test LDAP Settings.
  • Enter your LDAP Server URL, the exact security principal to pass to the server (no substitution takes place), and the password.
  • Check the box if you want to use SASL Authentication.
  • Click Test and an LDAP connect will be attempted.

As discussed above, the LDAP security principal must be in the format required by your LDAP server configuration.

If you're unfamiliar with LDAP or your organization's directory services configuration you should consult with your network administrator. You may also want to download an LDAP client browser to view and test your LDAP network servers. The Softerra LDAP Browser is a freeware product that you can use to browse and query your LDAP servers; visit the Softerra download page and click the "LDAP Browser #.#" tab.

LDAP Search Option

If your LDAP system uses an additional mapping layer between email usernames and security principal account names, it is possible to configure LabKey Server to search for these account names prior to authentication. For example, a username that the LDAP server accepts for authentication might look like 'JDoe', while a user's email address is ''. Once this alternate mode is activated, instead of an LDAP template, you would provide credentials and a source database in which to look up the security principal account names. To enable:

  • Add LDAP configuration settings to the labkey.xml configuration file, inside the <context> element. For example:
<Environment name="ldapSearch_username" value="" type="java.lang.String" override="false"/>
<Environment name="ldapSearch_password" value="***" type="java.lang.String" override="false"/>
<Environment name="ldapSearch_searchBase" value="dc=email,dc=org" type="java.lang.String" override="false"/>
<Environment name="ldapSearch_lookupField" value="userPrincipalName" type="java.lang.String" override="false"/>
<Environment name="ldapSearch_searchTemplate" value="(&amp;(objectClass=user)(userPrincipalName=${email}))"
type="java.lang.String" override="false"/>
    • "ldapSearch_username" is the email address of the LDAP user who has permission to "search" your LDAP directory.
    • "ldapSearch_password" is the password for the LDAP user specified with "ldapSearch_username"
    • "ldapSearch_searchBase" is the searchBase to be used. This could be the root of your directory or the base which contains all of your user accounts.
    • "ldapSearch_lookupField" is the optional field to use as a login following the LDAP search. (Default: "sAMAccountName")
    • "ldapSearch_searchTemplate" is the optional filter to apply during the LDAP search. Valid substitution patterns are ${email} and ${uid}. (Default: "(&(objectClass=user)(mail=${email}))")
  • Restart your Tomcat server.

When this is properly configured, when a user attempts to authenticate to the LabKey Server, the server connects to the LDAP server using the "ldapSearch_username" and "ldapSearch_password" in the labkey.xml file. It will use "ldapSearch_searchBase" as the search base, and look for any LDAP user account which is associated with the email address provided by the user (optionally, a custom filter may be used by specifying "ldapSearch_searchTemplate"). If a matching account is found, the LabKey Server makes a separate authentication attempt using the value of the "ldapSearch_lookupField" field from the LDAP entry found and the password provided by user at the login screen.

Related Topics


Was this content helpful?

Log in or register an account to provide feedback

expand all collapse all