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

Time-based One-Time Password (TOTP) two-factor authentication (2FA) is an additional layer of security beyond the primary authentication method. A mobile device or an authenticator app (such as Microsoft Authenticator or Google Authenticator) generates one-time passwords (OTP), which the user needs in addition their password to complete the authentication process. The time-based one-time password is valid only for a specified 'time step', defaulting to 30 seconds. After this interval passes, a new password is generated.

Note that basic username/password authentication is disabled when two-factor authentication is enabled. API keys or session-specific keys are required for using the LabKey APIs when TOTP two-factor authentication is enabled.

Configure TOTP 2 Factor Authentication

An administrator configures TOTP 2FA on the server. This step must only be performed once.

  • 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 > TOTP 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 TOTP 2FA configurations, make sure this description will be unique.
  • Issuer Name: Name of this LabKey deployment. This name will be displayed in every user's authenticator app.
  • Click Finish to save.

Only one TOTP 2FA configuration can be defined. If needed, you can edit it, including to enable and disable if you want to control when it is in use.

Set Up Authenticator App

Once enabled, every user will see a secondary authentication screen when they attempt to log into the server. After providing their username and password, the server's property store is checked to see if a "Secret Key" exists for that user. If it does not, either because this is the first time they have logged in using TOTP or because the key has been reset by an administrator, the user will need to set up their authenticator app using a QR code.

After providing their username and password, the user clicks Sign In and will see the QR code and generated "Secret Key" specific to them.

Consider copying and saving this Secret Key for future reference. If you lose access and need it later for some reason, you will have to have this key reset.

Open your authenticator app and scan the QR code to add this server. Once added, the app will start generating time-based passcodes. Enter the current code generated into the One-Time Password box and click Submit to complete logging in.

Log In with TOTP Code

Once the the user has set up the authenticator app, when they log in again, they will again sign in with username and password, then on the secondary authentication page will only see a prompt for the One-Time Password shown in the app. Click Submit to log in.

Note that if you have not completed the login before the time expires, you may need to regenerate a new one-time password.

Reset TOTP Secret Key

If the user needs to have their "Secret Key" reset for any reason, an administrator can edit the user details and click Reset TOTP Settings.

The next time this user logs in, they will need to set up their authenticator app again with a new QR code and secret key.

Troubleshooting Disable

The preferred way to disable two-factor authentication is through the web interface as described above. If problems with network connectivity, configuration, or other issues are preventing 2FA, and thereby effectively preventing all users from logging in, server administrators can disable TOTP 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.totp.Bypass" value="true" />

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

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all