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.

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 Set Up

To set up two-factor authentication, 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: 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.
• Click the Settings tab.
• Under Configuration, click Authentication.
• On the Authentication page, next to "Duo 2 Factor", click Configure.
• 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. The default is by User ID, but you can also match based on username or full email address. To match by username, the Duo user name must exactly match the LabKey Server display name.

• Click Test to verify these values.
• Click Save after the verification test is successful.

Enable Two-Factor Authentication

Finally, enable two-factor authentication on LabKey Server:

Disable Two-Factor Authentication

The preferred way to disable two-factor authentication is through the web interface:

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.xml or equivalent deployment descriptor in the Tomcat configuration directory:

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