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

LabKey Server can use your organization's LDAP (lightweight directory access protocol) 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.

Auto Create Authenticated Users

If a user is authenticated by the LDAP server but does not already have an account on the LabKey Server, the system can create one automatically. This is enabled by default but can be disabled using a checkbox in the global settings of the authentication page

Configure LDAP Authentication

To add a new LDAP configuration, follow these steps:

  • Select (Admin) > Site > Admin Console.
  • Under Configuration, click Authentication.
  • On the Authentication page, on the Primary tab, select Add New Promary Configuration > LDAP...
  • In the popup, configure the fields listed below.
  • After completing the configuration fields, you can click the Test button in the popup to test your LDAP authentication settings. See below.
  • Click Finish to save the configuration.
  • Configuration Status: Click the slider to switch between Enabled and Disabled.
  • Description: Enter a unique descriptive label for this configuration. If you plan to define multiple configurations for this provider, so be sure to use a description that will help you differentiate.
  • 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.
  • 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.
    • If you are using LDAP Search, please refer to the LDAP Search section for the correct substitution syntax.
  • Use SASL authentication: Check the box to use SASL authentication.
  • Use LDAP Search: The LDAP Search option is rarely needed. It is useful when the LDAP server is configured to authenticate with a user name that is unrelated to the user's email address. Checking this box will add additional options to the popup as described 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 some sample LDAP security principal templates:

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

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.
  • If you are using LDAP Search, please refer to the LDAP Search section for the correct substitution syntax.

Edit, Enable/Disable, and Delete Configurations

You can define as many LDAP configurations as you require. Be sure to use descriptions that will help you differentiate them. Use the six-block handle on the left to reorder the login form configurations. Enabled configurations will be used in the order they are listed here.

To edit an existing configuration, click the (pencil) icon on the right.

Click the Configuration Status slider in the edit popup to toggle between Enabled and Disabled.

To delete a configuration, click the on the right.

Testing the LDAP Configuration

It is good practice to test your configuration during creation. If you want to reopen the popup to test later, click the (pencil) icon for the configuration to test.

  • From the LDAP Configuration popup, click Test.
  • 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 name, or alternately a "Lookup field" value to use instead. This "Lookup field" value would be used for your substitution syntax for the LDAP Principal Template.

To enable:

  • Search DN: Distinguished Name of the LDAP user that will be used to search the LDAP directory.
  • Password: Password for the LDAP user specified as "Search DN".
  • Search base: Search base to use. This could be the root of your directory or the base that contains all of your user accounts.
  • Lookup field: User record field name to use for authenticating via LDAP. The value of this field will be substituted into the principal template to generate a DN for authenticating. In the above image, the principal template uses only this field but you could also use something more complex like "uid=${sAMAccountName},dc=example,dc=com".
  • Search template: Filter to apply during the LDAP search. Valid substitution patterns are ${email} and ${uid}.

  • After entering the appropriate values, you can test the configuration.
  • Click Apply to save the changes.
  • Click Save and Finish to exit the authentication page.

When this is properly configured, when a user attempts to authenticate to the LabKey Server, the server connects to the LDAP server using the "Search DN" and "Password". It will use the search base you specified, and look for any LDAP user account which is associated with the email address provided by the user (applying any filter you provided as the "Search template"). If a matching account is found, the LabKey Server makes a separate authentication attempt using the value of the "Lookup 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