LabKey Server can use your organization's LDAP server to authenticate users. The advantage to using LDAP for authentication is that you don't need to add individual users to LabKey and your 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.
Configure LDAP Authentication
To configure LDAP, follow these steps:
- Select Admin > Site > Admin Console.
- On the Site Administration page, click Authentication.
- On the Authentication page, next to LDAP, click Configure.
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://servername.domain.org:389, where 389 is the standard port for non-secured LDAP connections. The standard port for secure LDAP (LDAP over SSL) is 636. Please 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.
LDAP Domain: A domain name (e.g., "labkey.org") that determines if LabKey attempts LDAP authentication. When a user enters an email address that ends in this domain, LabKey Server attempts LDAP authentication; for all other email addresses, LabKey Server skips LDAP authentication. 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 DN (distinguished name) such as:
uid=myuserid,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.
Enable LDAP Authentication
Once you have configured an LDAP server for LabKey Server to use, you can enable it:
- To configure LDAP authentication, select Admin > Site > Admin Console.
- On the Site Administration page, click Authentication.
- On the Authentication page, next to LDAP, click Enable.
Authentication Process
When a user logs into LabKey with an email address ending in the LDAP domain, LabKey attempts an LDAP connect to the server(s) using the security principal and password the user just entered. If the LDAP connect succeeds, the user is authenticated; if the LDAP connect fails, LabKey attempts authenticating the credentials using database authentication. See
Authentication for more details about the authentication process.
Note: When configuring LabKey to use an LDAP server you are trusting that the LDAP server is both secure and reliable.
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:
| Property | Substitution Value |
|---|
| ${email} | Full email address entered on the login page, for example, "myname@somewhere.org" |
| ${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:
| Server | Sample Security Principal Template |
|---|
| Sun Directory Server | uid=${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 X.Y" 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 'JEckels', while a user's email address is 'josh.eckels@labkey.com'. 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="ldapAdmin@email.org" 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="(&(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.
