TOTP Two-Factor Authentication

In this article, we're going to enable Strong Two-Factor Authentication using Time-Based One Time Password Authentication (TOTP). Sometimes this is called app authentication using authenticator apps like Authy, Google Authenticator, Microsoft Authenticator and similar. There's clients for almost any type of clients. Modern password managers like 1Password and LastPass also includes TOTP authenticator clients. The standard for TOTP is defined in RFC6238.

Video Overview

Please see the following video overview of using TOTP Strong Two-Factor Authentication:

Configuration

There's no requirement for any configuration to enable TOTP Authentication. You can configure a friendly name if you want in Admin → Configuration → Strong Auth TOTP.

In order to enable your users to use TOTP Authentication, you can choose to enable or require TOTP Authentication on a per group basis in Admin → Groups:

The default configuration for all groups is TOTP Enable. If you select TOTP Enable, users can enable TOTP Strong Two-Factor Authentation if they want. If you select TOTP Require, users will require to use TOTP Strong Two-Factor Authentication.

Remember Strong Authentication

If you enable Remember Strong Authentication (see screenshot above), users will be presented with a checkbox to remember, or skip, strong authentication for 2 weeks.

Exclude Networks

Configuring Exclude Networks (see screenshot above) will enable you to skip Strong Authentication for specified networks, typically your internal networks.

User Configuration

If you have selected TOTP Enable for a group of users, users in that group can enable TOTP Authentication by going to Account Settings and the Two-Factor Authentication Tab:

If you have selected TOTP Require, users will be required to configure TOTP using a similar screen next time they login.

Please see the Video Overview above to see the user experience.

Troubleshooting

Wrong Code

The first potential problem is that the user needs to enter the correct TOTP code.

Wrong Time

The first T in TOTP is Time. When authenticating, LiquidFiles has a 1 minute grace period but if either the client or the server time differs more than that, the authentication will fail. We've for instance seen issues where the server gets fed wrong time from its host. If you're running LiquidFiles in VMware and the VMware host's time is wrong, VMware Tools is more agressive at setting time than NTP so it will force the LiquidFiles system to run with the wrong time. If the time is wrong on the VM host it will almost certainly lead to TOTP authentication failures.

Incorrect Secret

With TOTP there's a shared secret. In the screenshot above, it's in the QR code and you can also see it where it says "enter the following code".

You can get an incorrect secrect if the user scans the QR code but never enters the code to validate it. If the user tries to use this secret next time it will always fail. The shared secret will be randomized each time the user attempts to setup TOTP until the user successfully validates the secret. If the user tries to setup TOTP multiple times, they will need to remove the previous TOTP configuration for the LiquidFiles before each attempt.

In Admin → Users, when you edit a user that uses TOTP, as an Admin you can reset the users TOTP code. If you do, next time the user will be prompted to setup a new TOTP authentication but if they don't realize and try to use their previous saved secret, authentication will fail.

TOTP Clients

Since TOTP is based on an open standard, there are many available clients for a variety of systems. Here are some examples in alphabetical order: