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