Maintenance Notice: labkey.org will be offline at 10:00 AM Pacific Time on Sunday, July 14th 2024 for maintenance. The estimated downtime should be no more than one hour. Please save your work before this time. We apologize for any inconvenience.
This topic is under construction for the 24.7 (July 2024) release. For current documentation of this feature, click here.

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 when TOTP 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.

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.
  • Require TOTP for:
    • All users (Default)
    • Only users assigned the "Require Secondary Authentication" site role.
  • 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, or for which users/groups.

Set Up Authenticator App

Once enabled, users 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

Disable 2FA Temporarily

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 temporarily editing the application.properties 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 application.properties file, commenting out that line again and restarting.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback

expand allcollapse all