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 attempts to authenticate the user via the next LDAP server on the list.
- 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, described below the image, 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 address(es) 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.
- 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., "labkey.com"), 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: LDAP principal template that matches the DN requirements of the configured LDAP server(s).
- The template supports substitution syntax; include ${email} to substitute the user's full email address, ${uid} to substitute the username part of the user's email address, all fields from the user's row in the core.SiteUsers, and, if using LDAP Search, the name of the Lookup field.
- Different LDAP servers require different authentication templates so check with your LDAP server administrator for specifics.
- 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.
- Read LDAP attributes: This option is rarely needed. It is useful when RStudio Pro integration requires authentication via an LDAP attribute that is unrelated to the user's email address. If this option is configured, the "Test" action will read and display all user attributes.
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:
- LDAP Server URL: This is typically of the form ldap://servername.domain.org
- Security Principal: This varies widely by vendor and configuration. A couple starting points:
- Microsoft Active Directory requires just the email address (shown below).
- Other LDAP servers typically require a more detailed DN (distinguished name) such as: uid=myuserid,ou=people,dc=mydomain,dc=org your LDAP Server URL, the exact security principal to pass to the server (no substitution takes place), and the password.
- Match any SASL and LDAP Attribute settings required for the test.
- Check the box if you want to use SASL Authentication.
- Click Test and an LDAP connect will be attempted. You should see a success message at the top of the page, otherwise you may need to adjust your settings.
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.
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 ${email}, ${uid}, and all fields from the user's row in the core.SiteUsers table.
- 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.
Read LDAP Attributes
In specific deployments, you may need to use LDAP attributes in order to provide RStudio with an alternative login ID. If enabled and configured, LabKey will read a map of LDAP attributes at authentication time.
Additional fields will be shown.
- Attribute search base: Search base to use when reading attributes. This could be the root of your directory or the base that contains all of your user accounts.
- Attribute search filter template: Filter to apply while reading attributes. Valid substitution patterns are ${email}, ${uid}, and, if using LDAP Search, the name of the Lookup field.
Troubleshooting
If you experience problems with LDAP authentication after upgrading Java to version 17.0.3, they may be related to Java being stricter about LDAP URLs. More detail is available in this Java release note:
The logs may show an error message similar to:
ERROR apAuthenticationProvider 2022-04-27T08:13:32,682 http-nio-80-exec-5 : LDAP authentication attempt failed due to a configuration problem. LDAP configuration: "LDAP Configuration", error message: Cannot parse url: ldap://your.url.with.unexpected.format.2k:389
Workarounds for this issue include using a fully qualified LDAP hostname, using the IP address directly (instead of the hostname), or running Java with the "legacy" option to not apply the new strictness:
-Dcom.sun.jndi.ldapURLParsing="legacy"
Related Topics
