LabKey Server can use your organization's LDAP (lightweight directory access protocol) server(s) to authenticate users. The permissions a user will have are the permissions given to "Logged in users" in each project or folder. Using LDAP for authentication has a number of advantages:
- You don't need to add individual users to LabKey
- 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 an LDAP server, any user in the LDAP domain can log on to your LabKey application. You can change this default behavior by
disabling the auto-creating of user accounts.
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 configuring LabKey to use any LDAP server you are trusting that the LDAP server is both secure and reliable.
When a user logs into LabKey with an email address ending in the
LDAP domain you configure, the following process is followed:
- LabKey attempts to connect to each LDAP server listed in LDAP Server URLs, 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).
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 Primary Configuration > LDAP...
- In the popup, configure the fields listed below.
- After completing the configuration fields, click Test 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 Server URLs: 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. 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 with this configuration. Set this to an email domain (e.g., "labgroup1.org"), or use '*' to attempt LDAP authentication on all email addresses entered, regardless of domain.
- Multiple LDAP configurations can be defined to authenticate different domains. All enabled LDAP configurations will be checked and used to authenticate users.
- LDAP Principal Template: The LDAP principal template that describes the user attempting to authenticate. The default value is ${email}. Other LDAP servers require different authentication templates so check with your LDAP server administrator for specifics. The template supports substitution syntax; see section below for details.
- 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, and must include at least one substitution token so that the authenticating user is passed through to the LDAP server.
| Property | Substitution Value |
|---|
| ${email} | Full email address entered on the login page, for example, "myname@somewhere.org" |
| ${uid} | User name portion (before the @ symbol) of email address entered on the login page, for example, "myname" |
| ${firstname} | The value of the FirstName field in the user's record in the core.SiteUsers table |
| ${lastname} | The value of the LastName field in the user's record in the core.SiteUsers table |
| ${phone} | The value of the Phone field in the user's record in the core.SiteUsers table |
| ${mobile} | The value of the Mobile field in the user's record in the core.SiteUsers table |
| ${pager} | The value of the Pager field in the user's record in the core.SiteUsers table |
| ${im} | The value of the IM field in the user's record in the core.SiteUsers table |
| ${description} | The value of the Description field in the user's record in the core.SiteUsers table |
- Custom fields from the core.SiteUsers table are also available as substitutions based on the name of the field. For example, "uid=${customfield}"
- If LDAP Search is configured, the lookup field is also available as a substitution. For example, "uid=${sAMAccountName}"
Here are some sample LDAP security principal templates:
| Server | Sample Security Principal Template |
|---|
| Microsoft Active Directory Server | ${email} |
| OpenLDAP | cn=${uid},dc=myorganism,dc=org |
| Sun Directory Server | uid=${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 'jane.doe@labkey.com'. Once this alternate mode is activated, instead of an LDAP template, you would provide credentials and a source database in which that credential can 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 account that will search the LDAP directory. This account must have access to the LDAP server URLs specified for this configuration.
- 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 as described above.
- After entering the appropriate values, click Test to validate 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" credential 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
