TOTP multi-factor authentication

Upgrade to Latest Version

Introduction

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 is a standard that many devices and applications support for Multi-Factor Authentication (MFA). It is designed so that users will need to have their credentials as well as a device or app that generates temporary MFA codes required to complete the login process. This documentation provides you with:

  1. Steps on how to enable TOTP 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. Some restrictions on the use of TOTP MFA in Access Server.
  5. Helpful information about MFA for autologin profiles and bootstrap users.

Examples of TOTP MFA applications for setting this up include Google Authenticator, Microsoft Authenticator, Yubikey Authenticator, Gnome Authenticator, FreeOTP, andOTP, and others. Since it is a standard, many devices and apps support this. There are also standalone hardware devices that support this and work with Access Server such as the Protectimus Slim NFC token.

Note: If you use SAML as your authentication method, ensure you setup MFA with your SAML IdP and not by enabling the TOTP MFA toggles in the Admin Web UI.

How to enable TOTP Multi-Factor Authentication for all users

TOTP multi-factor authentication isn’t enabled by default for OpenVPN Access Server. You can enable it for all users, or by individual groups and users (for Access Server 2.11.1 and newer).

To enable it globally:

  1. Sign in to your Admin Web UI.
  2. Click Authentication > Settings.
  3. Set Enable TOTP Multi-Factor Authentication to Yes.
    (called Enable Google Authenticator MFA in older Access Server versions)
  4. Click Save Settings and Update Running Server.

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 MFA shared key in QR code and plaintext.
  3. Scan the QR code or enter the key manually into the TOTP app or device.
  4. Enter the six-digit one-time password provided by the TOTP app or device.
  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. To enable TOTP MFA for a specific user or group only, you must do this from the command line. Refer to the commands in the section below, “Command line configuration parameters.”

How to enable TOTP MFA for user and groups

On Access Server 2.11.1 and newer, you can enable TOTP MFA for individual users and groups from the Admin Web UI.

To enable it for groups:

  1. Sign in to your Admin Web UI.
  2. Click User Management > Group Permissions.
  3. Click More Settings for the desired group.
  4. Click the radio button to enable or disable TOTP-based Multi-Factor Authentication for the group.
  5. Click Save Settings and Update Running Server.

To enable it for users:

  1. Sign in to your Admin Web UI.
  2. Click User Management > User Permissions.
  3. Click More Settings for the desired user.
  4. Click the radio button to enable or disable TOTP-based Multi-Factor Authentication for the user.
  5. 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.

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 six-digit code that is valid only during a short timeframe, and changes afterwards. When TOTP MFA was first implemented in Access Server it was referred to as Google Authenticator MFA and there may still be some leftovers in documentation and instructions referring to that. TOTP MFA is however a standard that many apps and devices adhere to and newer Access Server releases refer to it as such.

Google Authenticator, for example, is an application to manage your shared secrets—shared keys agreed upon between the server and a device on the user's side. A calculation based on the shared key and current date and time yields a six-digit code. The server and the user's device both do this calculation. During login, the user sends the result from its own device to the server, and the user successfully signs in when the results match. To accommodate minor deviations in time drift, we allow codes immediately preceding and following the current code to authenticate with Access Server successfully.

It’s important to know that both the shared key and the date and time must match on the server and the device that generates the six-digit codes on the user's side. Thus, if either the server or device has the date or time wrong, or the shared key is not the same, then 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. Please ensure that client devices also keep accurate time.

Transferring the shared key from the server to the client takes place by scanning a QR code or entering the shared key manually during the enrollment process. OpenVPN Access Server provides this to the user upon logging in to the Client Web UI when they are not yet enrolled. They are then required to complete the enrollment process by scanning or entering the shared key on their device that generated the TOTP MFA codes, and then confirming that enrollment completed successfully by entering a valid six-digit code generated on their device. Once enrolled, a user will need to enter their credentials followed by a valid six-digit code in order to authenticate for future login sessions.

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
./sacli start

Enable TOTP MFA for a specific user or group:

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

Enable TOTP MFA for all auto-login profiles:

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

Remove the setting and restore default behavior:

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

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

./sacli --user <USER> --lock 0 TotpLock
./sacli start

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

./sacli --user <USER> --lock 1 TotpLock
./sacli start

See the current MFA shared key for a particular user:

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

Check if MFA shared key is locked in — a 1 or true means it's locked:

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

Generate new MFA unlocked shared key so the user can enroll on the web interface:

./sacli --user <USER> --lock 0 TotpRegen
./sacli start

Generate a new MFA locked shared key so the user can't enroll on the web interface:

./sacli --user <USER> --lock 1 TotpRegen
./sacli start

Note: The commands TotpLock, TotpRegen, and TotpGet work on Access Server 2.11 and newer. For older Access Server versions you'll have to use the old names GoogleAuthLock, GoogleAuthRegen, and GoogleAuthGet instead.

The TotpLock and TotpRegen 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 are offered the MFA shared key in QR code and plaintext format in order to add it to their device or app that will generate the six-digit codes TOTP MFA codes for them. The user is required to then enter a valid six-digit code to ensure that the enrollment procedure was successful. After doing this the user is considered successfully enrolled and the MFA shared key can no longer be requested from the server. The user will now have to use their credentials and the six-digit code generated by their device to log in successfully.

If a user loses their device or it’s compromised, use the sacli TotpRegen 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 TotpRegen and TotpGet commands generate 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.

Restrictions on TOTP MFA in Access Server

If you are using a post-auth script to enhance or replace your authentication process in the Access Server, please note that MFA implemented in the post-auth script cannot be used alongside the built-in TOTP MFA function of the Access Server itself. You have to choose to use either the built-in MFA method or implement one yourself in the post-auth script instead.

Adding TOTP MFA to users logging in through SAML is not supported. If you have a requirement for MFA for your SAML users, then please implement this on the SAML IDP itself. If you attempt to apply TOTP MFA in the Access Server on SAML users, these users will not be able to log in and an error message will be produced when you attempt to do so. You can disable the TOTP MFA requirement either globally or on the individual users or groups that are configured to log in via SAML.

On Access Server 2.9 and older the bootstrap administrative accounts as defined in the as.conf configuration file will bypass the MFA requirement as well as the password lockout policy. It is recommended that you upgrade your Access Server so that any MFA requirement and password lockout policy will also apply to these accounts. There is more information on the bootstrap accounts and MFA below.

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.