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

Two-Factor Authentication (2FA) is an additional security layer which requires users to perform a second authentication step after a successful primary authentication (username/password). The user is allowed access only after both primary and secondary authentication are successful.

LabKey Server supports two-factor authentication through integration with Duo Security. Duo Security provides a variety of secondary authentication methods, including verification codes sent over SMS messages, audio phone calls, and hardware tokens. LabKey Server administrators who wish to take advantage of two-factor authentication will need to open a paid account with Duo Security -- although evaluation and testing can be accomplished with a free trial account. Most of the configuration decisions about the nature of your two-factor authentication service occur within the Duo Security account, not within LabKey Server.

Two-factor authentication requires users to provide an additional piece of information to be authenticated. A user might be required to provide a six-digit verification code (sent to the user's cell phone over SMS) in addition to their username/password combination. The second credential/verification code is asked for after the user has successfully authenticated with LabKey Server's username/password combination. For example, the screenshot below shows the secondary authentication step once a verification passcode that has been sent to his/her cell phone via SMS/text message, voice call, or the Duo mobile application:

Note that when Duo two-factor authentication is enabled, you must use an API key or session-specific key to access data via the LabKey APIs, as there is no way to provide a second factor with a username/password.

Duo Security Setup

To set up Duo 2FA, administrator permissions are required. You first sign up for a Duo Administrator account at the following location:

Next, you specify how Duo will enroll users, and acquire the necessary information to configure LabKey Server:

  • Login to Duo at:
  • On the Duo website, select Applications > New Application.
  • On the Application Type dropdown select "Web SDK" and provide an Application Name of your choice.
  • Click Create Application.
  • Once the Duo Application has been created, you will be provided with an Integration Key, Secret Key, and an API Hostname, which you will use to configure LabKey Server.
  • Under Policy, specify the options for how users will be enrolled in Duo.

Configure Two-Factor Authentication on LabKey Server

  • Select (Admin) > Site > Admin Console.
  • Under Configuration, click Authentication.
  • On the Authentication page, click the Secondary tab in the Configurations panel.
  • Select Add New Secondary Configuration > Duo 2 Factor...
  • Note the Configuration Status is Enabled by default. Click the toggle to disable it.
  • Description: This field is used as the name in the interface. If you will create multiple duo configurations, make sure this description will be unique.
  • Enter the following values which you acquired in the previous step:
    • Integration Key
    • Secret Key
    • API Hostname
    • User Identifier: Select how to match user accounts on LabKey Server to the correct Duo user account. Options:
    • User ID (Default)
    • User Name: To match by username, the Duo user name must exactly match the LabKey Server display name.
    • Full Email Address.
  • Click Finish in the popup to save.

If desired, you can add additional two-factor authentication configurations. Multiple enabled configurations will be applied in the order they are listed on the Secondary tab. Enable and disable them as needed to control which is in use at a given time.

Edit Configuration

To edit the configuration:

  • Select (Admin) > Site > Admin Console.
  • Under Configuration, click Authentication.
  • Click the Secondary tab.
  • Next to the Duo 2 Factor configuration name you want to edit, click the (pencil} icon to open it.
  • After making any changes needed, click Apply.
  • Click Save and Finish to exit the authentication page.

Enable/Disable Two-Factor Authentication

When you view the Secondary tab you can see which configurations are enabled. To change the status, open the configuration via the (pencil) and click the Configuration Status slider to change between Enabled and Disabled.

Click Apply to save changes, then click Save and Finish to exit the authentication page.

Delete Duo Configuration

To delete a configuration, locate it on the Secondary tab and click the (delete) icon. Click Save and Finish to exit the authentication page.


Disable 2FA Temporarily

The preferred way to disable two-factor authentication is through the web interface as described above. If problems with network connectivity, Duo configuration, billing status, or other similar issues are preventing two-factor authentication, and thereby effectively preventing all users from logging in, server administrators can disable the Duo integration by temporarily editing the file to uncomment this line:


After the line is added, restart the LabKey Server, and then all users will be able to log in without giving a second factor. Be sure to resolve the connection issue and restore 2FA by returning to edit the file, commenting out that line again and restarting.

Duplicate Key During Upgrade

In 23.11, the "duo" module was moved to the "mfa" (multi-factor authentication) module. If you see an error that begins like:

Duplicate key {helpLink=, saveLink=/labkey/duo-duoSaveConfiguration.view, settingsFields=[{"name":"integrationKey","caption":"Integ...
...this means you have both the "duo" and "mfa" modules duplicating the attempt. To resolve:
  • Stop Tomcat
  • Delete the "duo" module (and any other outdated/invalid modules) from your deployment.
  • Start Tomcat
  • Go to the > Site > Admin Console.
  • On the Module Information tab, click Module Details.
  • Scroll down to the Unknown Modules section and delete the "duo" module and schema from here to delete the duplicate from the database.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all