Configure Duo Two-Factor Authentication

 2024-04-18
Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

Two-Factor Authentication 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.

Note that basic username/password authentication is disabled if Duo authentication is enabled. API keys or session-specific keys are required for using the LabKey APIs when Duo is enabled.
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:

Duo Security Setup

To set up two-factor authentication, administrator permissions are required. You first sign up for a Duo Administrator account at the following location:

https://signup.duosecurity.com

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

  • Login to Duo at: https://admin.duosecurity.com/login
  • 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 duo 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.

Troubleshooting Disable

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 adding a line to the LabKey configuration file in the Tomcat configuration directory (labkey.xml or ROOT.xml):

<Parameter name="org.labkey.authentication.duo.Bypass" value="true" />

After the line is added, restart Tomcat, and then all users will be able to log in without giving a second factor.

Related Topics