Tutorial: How to Manage TOTP MFA from the Command Line

Abstract

Enable TOTP multi-factor authentication to increase the security of Access Server VPN client connections.

Overview

You can add another security layer for users signing in to Access Server with Time-based One-Time Passwords (TOTP). Many devices and applications support this standard for Multi-Factor Authentication (MFA). It is designed so that users will need to have their credentials and a device or app that generates temporary MFA codes to complete the login process.

This tutorial covers turning on TOTP MFA from Access Server's Admin Web UI.

You can read about Access Server's TOTP MFA feature in this topic.

Prerequisites

An installed Access Server.
Console access and the ability to get root access.
A TOTP MFA application such as Google Authenticator, Microsoft Authenticator, Yubikey Authenticator, Gnome Authenticator, Free OTDP, andOTP, etc. There are also standalone hardware devices that support this and work with Access Server, such as the Protectimus Slim NFC token.

Step 1: Sign on to the console

Sign on to the console and get root privileges.
Change to the scripts directory to use the sacli tool to run commands:
```
cd /usr/local/openvpn_as/scripts/
```

Step 2: Run your desired commands

Use the sacli commands below to manage TOTP MFA for Access Server:

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 the 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 a 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
```

Important

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

In this section: