This topic is under construction for the 24.10 (October 2024) release. For the previous version of this documentation, click here.
User authentication is performed through LabKey Server's core database authentication system by default.
Authentication means identifying the user to the server. In contrast, user
authorization is handled separately, by an administrator
assigning roles to users and groups of users.
With Premium Editions of LabKey Server, other authentication methods including LDAP, SAML and CAS single sign-on protocols, and TOTP or Duo two-factor authentication can also be configured. Premium Editions also support defining multiple configurations of each external authentication method.
Learn more about Premium Editions here.
Authentication Dashboard
To open the main authentication dashboard:
- Select (Admin) > Site > Admin Console.
- Under Configuration, click Authentication.
- Global Settings: Use checkboxes to enable either or both option.
- Configurations: There are two tabs for configurations:
- Primary: The default primary configuration is Standard database authentication.
- On servers where additional authentication methods are enabled, you can use the Add New Primary Configuration dropdown.
- Secondary: Use this tab to configure a secondary authentication method for two factor authentication, such as Duo. When configured, the secondary configuration will be used to complete authentication of users who pass a primary method.
- Login Form Configurations: These configurations make use of LabKey's login page to collect authentication credentials. Standard database authentication uses this method. If additional configuration methods are added, such as LDAP on a Premium Edition server, LabKey will attempt authenticating against each configuration in the order they are listed. You can drag and drop to reorder them.
- Single Sign-On Configurations: Configurations in this section (if any) let LabKey users authenticate against an external service such as a SAML or CAS server. LabKey will render custom logos in the header and on the login page in the order that the configurations are listed. You can drag and drop to reorder them.
Allow Self Sign Up
Self sign up allows users to register for new accounts themselves when using database authentication. When the user registers, they provide their own email address and receive an email to
choose a password and sign in. If this option is disabled, administrators must create every user account.
When enabled via the authentication page, users will see a
Register button on the login page. Clicking it allows them to enter their email address, verify it, and create a new account.
When self sign up is enabled, users will need to correctly enter a captcha sequence of characters before registering for an account. This common method of 'proving' users are humans is designed to reduce abuse of the self sign up system.
Use caution when enabling this if you have enabled sending email to non-users. With the combination of these two features, someone with bad intent could use your server to send unwanted spam to any email address that someone else attempts to 'register'.
Allow Users to Edit Their Own Email Addresses (Self-Service Email Changes)
Administrators can configure the server to allow non-administrator users to change their own email address (for configurations where user passwords are managed by LabKey Server and not by any outside authority). To allow non-administrator users to edit their own email address, check the box to
Allow users to edit their own email addresses. If this box is not checked, administrators must make any changes to the email address for any user account.
When enabled uses can edit their email address by selecting
(User) > My Account. On the user account page, click
Change Email.
System Default Domain
The
System Default Domain specifies the default email domain for user ids. When a user tries to sign in with an email address having no domain, the specified value will be automatically appended. You can set this property as a convenient shortcut for your users. Leave this setting blank to always require a fully qualified email address.
Multiple Authentication Configurations and Methods
Premium Features — The ability to add other authentication methods and to define multiple configurations of each method is available with all Premium Editions of LabKey Server.
Learn more or
contact LabKey.
Multiple authentication methods can be configured simultaneously, which provides flexibility, failsafe protections, and a convenient way for different groups to utilize their own authentication systems with LabKey Server. For example, standard database authentication, an LDAP server, and SAML can simultaneously be used.
For each external method of authentication used with Premium Editions of LabKey Server, there can also be multiple distinct configurations defined and selectively enabled. For example, the following server has 5 available configurations, 3 of which are enabled.
When multiple configurations are available, LabKey attempts to authenticate the user in the order configurations are listed on the
Primary tab, followed by the
Secondary tab. You can rearrange the listing order by dragging and dropping using the six-block handles on the left.
If any one configuration accepts the user credentials, the login is successful. If all enabled configurations reject the user's credentials, the login fails. This means that a user can successfully authenticate via multiple methods using different credentials. For example, if a user has both an account on a configured LDAP server and a database password then LabKey will accept either. This behavior allows non-disruptive transitions from database to LDAP authentication and gives users an alternate means in case the LDAP server stops responding or its configuration changes.
When
migrating users from LDAP to the database authentication method, you can monitor progress using the "Has Password" field on the
Site Users table.
Supported Authentication Methods
- Database Authentication - LabKey Server's built-in database authentication service.
- LDAP: (Premium Feature) Configure LDAP servers to authenticate users against an organization's directory server.
- SAML: (Premium Feature) Configure a Security Assertion Mark-up Language authentication method.
- CAS: (Premium Feature) Authenticate users against an Apereo CAS server.
- Duo: (Premium Feature) Secondary authentication using Duo.
- TOTP: (Premium Feature) Secondary authentication using a Time-based One-Time Password (TOTP) authenticator.
Auto-create Authenticated Users
If one or more remote authentication methods is enabled, you will see an additional checkbox in the
Global Settings. By default, new LabKey Server accounts will be automatically created for users who are authenticated by external methods such as LDAP, SAML, or CAS. You can disable it in the global settings by unchecking the box.
If you disable auto creation of authenticated users, be sure to communicate to your users the process they should follow for creating a LabKey account. Otherwise they will be able to authenticate but will not have an actual LabKey account with which to use the server. As one example process, you might require an email request to a central administrator to create accounts. The administrator would create the account, the activation email would invite the user to join the server, and they would be authenticated via the external configuration.
Enable/Disable and Delete Configurations
You cannot disable or delete the basic standard database authentication. When other configurations are available, you can use the toggle available at the top of the settings panel to enable/disable them. Click the
(pencil) to edit settings. Click the
to delete a configuration.
Note that you can save a partial configuration if it is disabled. Any fields provided will be validated, but you can save your work while still missing some information in order to make it easier to complete later.
Selectively Require Secondary Authentication
When using either TOTP or Duo Secondary Authentication (2FA), it can be useful to selectively apply the 2FA requirement to different users and groups. For example, you could roll out 2FA to separate departments at different times, or requiring 2FA only for users granted higher levels of administrative access.
By default when enabled, 2FA is applied to all users. To use it on a more selective basis:
- Grant the Require Secondary Authentication site role to the groups and users that need to use it.
- Edit the 2FA Configuration and set Require Duo/TOTP for: to "Only users assigned the "Require Secondary Authentication site role".
Related Topics
