TOTP multi-factor authentication


You have the option of adding another security layer for users signing in to OpenVPN Access Server with time-based one-time passwords (TOTP). This documentation provides you with:

  1. Steps on how to enable TOTP multi-factor authenticator (MFA) from the Admin Web UI.
  2. How TOTP MFA works with Access Server.
  3. Commands for setting up TOTP MFA from the command-line interface.
  4. Helpful information about MFA for autologin profiles and bootstrap users.

Examples of TOTP MFA applications for setting this up include Google Authenticator, Microsoft Authenticator, Gnome Authenticator, FreeOTP, andOTP, and others.

How to enable TOTP Multi-Factor Authentication

TOTP multi-factor authentication isn’t enabled by default for OpenVPN Access Server. To enable it globally:

  1. Sign in to your Admin Web UI.
  2. Click Authentication > Settings (or Client Settings on Access Server version 2.7.4 and older).
  3. Set Enable TOTP Multi-Factor Authentication to Yes. (This setting was previously called Enable Google Authenticator MFA in older versions of Access Server.)
  4. Click Save Settings and Update Running Server.

Note: If you use MFA added by post-auth script, enabling TOTP MFA will break user authentication. Ensure that no other MFA is enabled when enabling TOTP MFA.

Once enabled, users enroll from the Client Web UI.

To enroll with the Client Web UI:

  1. Sign in to the Client Web UI.
  2. The next screen displays the QR code and enrollment code.
  3. Scan the code or enter the enrollment code into the TOTP Authenticator app.
  4. Enter the six-digit one-time password provided by the TOTP Authenticator app.
  5. Click Confirm Code.

If a user doesn’t see the enrollment screen and only sees the one-time password prompt, you must generate a new MFA from the command line. Refer to “Command line configuration parameters” below for the command.

To enable TOTP MFA for a specific user or group, you must do this from the command line. Refer to the commands in the section below, “Command line configuration parameters.”

Operating principle and function

Apps such as Google Authenticator and Microsoft Authenticator use time-based one-time passwords (TOTP). When enabled for OpenVPN Access Server, your users enter their username and password first; then, they must enter a one-time password.

Google Authenticator, for example, is an application to manage your shared secrets—shared keys agreed upon between the server and client. A calculation based on the shared key and current date and time yields a six-digit code. The server and client both do this calculation, and the results match. During login, the client sends its result to the server, and the user successfully signs in when it matches.

It’s important to know that both the shared key and the date and time must match. Thus, if either the server or device has the date or time wrong, the authentication fails. Our prepared installation images include an NTP client program to synchronize time automatically via the internet to ensure OpenVPN Access Server has the correct time and date.

Ensure that client devices also keep accurate time and date.

As mentioned, you can use alternative apps to Google Authenticator as long as they are capable of generating TOTP codes. Microsoft Authenticator works as well as plugins for browsers and multi-factor one-time password devices.

Transferring the shared key from the server to the client takes place by scanning a QR code or entering an enrollment code. OpenVPN Access Server provides this to the user upon their first login to the Client Web UI. Once enrolled, a user enters their credentials followed by a six-digit code. The six-digit codes are valid for 30 seconds before a new code is generated.

To accommodate minor deviations in time drift, we allow codes immediately preceding and following the current code to authenticate with Access Server successfully.

Note: Using Google Authenticator doesn’t require connecting with Google's systems for generating unique shared codes, enrolling users, or generating six-digit response codes. Google Authenticator is simply a popular program that uses TOTP standard methods for MFA. You can find more information on the conceptual and technical aspects of Google Authenticator on this Google Authenticator WikiPedia page.

Command line configuration parameters

Use the following commands to configure TOTP MFA. To run these commands, sign in to your server with root privileges and run these from the directory, /usr/local/openvpn_as/scripts/.

Disable TOTP MFA globally for all users and groups (the default):

./sacli --key "vpn.server.google_auth.enable" --value "false" ConfigPut
./sacli start

Enable TOTP MFA globally for all users and groups:

./sacli --key "vpn.server.google_auth.enable" --value "true" ConfigPut
./sacli start

Disable TOTP MFA for a specific user or group:

./sacli --user <USER_OR_GROUP> --key "prop_google_auth" --value "false" UserPropPut

Enable TOTP MFA for a specific user or group:

./sacli --user <USER_OR_GROUP> --key "prop_google_auth" --value "true" UserPropPut

Remove the setting and restore default behavior:

./sacli --user <USER_OR_GROUP> --key "prop_google_auth" UserPropDel

Unlock the user's MFA code so the user can enroll on the web interface:

./sacli --user <USER> --lock 0 GoogleAuthLock

Lock the user's MFA code so the user cannot obtain/scan it on the web interface:

./sacli --user <USER> --lock 1 GoogleAuthLock

See the current MFA code in use for a particular user:

./sacli --pfilt <USER> UserPropGet | grep "pvt_google_auth_secret"

Check if MFA code is locked — a 1 or true means it's locked:

./sacli --pfilt <USER> UserPropGet | grep "pvt_google_auth_secret_locked"

Generate a new MFA code and unlock it so the user can enroll anew on the web interface:

./sacli --user <USER> --lock 0 GoogleAuthRegen

Generate a new MFA code and lock it so the user can't enroll on the web interface:

./sacli --user <USER> --lock 1 GoogleAuthRegen

The GoogleAuthLock and GoogleAuthRegen functions manage these two keys:

  • pvt_google_auth_secret — A 16-character alphanumerical value containing the MFA shared key.
  • pvt_google_auth_secret_locked — A value either true (1) or false (0) indicating enrollment is completed.

Initially, the MFA shared key is not locked. In this state, the user signs in to the Client Web UI. They use the MFA shared key to enroll. The TOTP MFA app uses the shared key to generate six-digit codes. After the user successfully enrolls, the shared key is locked, and the user must then enter their MFA key to sign in from then on.

If a user loses their device or it’s compromised, use the sacli GoogleAuthRegen command as shown in the examples above to generate a new unique secret key for their account. The old secret key no longer works. This command also unlocks the account TOTP MFA enrollment so that the user can enroll again. As an aside, the GoogleAuthRegen command also generates on the command line a string with otpauth:// URI format that can be used in a QR code generator. In the Client Web UI, Access Server already does this for the user, but this could be helpful for customized process automation.

Auto-login profiles and MFA

Server-locked and user-locked profiles both adhere to the requirement for multi-factor authentication. However, by default, auto-login profiles don’t adhere to this requirement. Typically, unattended devices—such as servers in datacenters establishing connections automatically—use auto-login profiles.

If you do wish to enable MFA on an auto-login profile, you can use this parameter:

./sacli --user <USER_OR_GROUP> --key "prop_google_auth_autologin" --value "true" UserPropPut
./sacli start

This requires all of the following:

  1. The user has auto-login privilege.
  2. An auto-login profile is installed on the VPN client.
  3. The VPN client is a modern VPN client such as OpenVPN Connect v3.3 or better.
  4. The requirement for MFA is enabled and configured for this user or group.

Bootstrap user accounts and MFA

OpenVPN Access Server 2.10 and newer

OpenVPN Access Server 2.10 and newer creates the openvpn account as an administrative user in the local user database. This account adheres to global account settings such as an MFA requirement and the password lockout policy. We recommend that you set your own strong password and enable MFA on this account.

OpenVPN Access Server 2.9 and older

OpenVPN Access Server 2.9 and older use a bootstrap administrative user account openvpn as defined in as.conf. The MFA security layer doesn’t apply to bootstrap users. Additionally, the password lockout policy isn’t triggered for the bootstrap user accounts. 

We recommend you avoid using bootstrap users for your administrative accounts and instead create a user in Access Server with admin privileges, enrolled with Google Authenticator. If you upgrade to Access Server 2.10 or newer you can set this administrative account up as a local user with the MFA requirement even if you’re using another authentication system for your users. You can then disable or remove bootstrap user accounts so they can’t sign in. Refer to these instructions on how to secure the openvpn administrative user account.