Tutorial: How to Manage TOTP MFA from the Command Line
Overview
You can add a 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.
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 OTP, etc. There are also standalone hardware devices that support this and work with Access Server, such as the Protectimus Slim NFC token.
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/
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 startEnable TOTP MFA globally for all users and groups:
./sacli --key "vpn.server.google_auth.enable" --value "true" ConfigPut ./sacli startDisable TOTP MFA for a specific user or group:
./sacli --user <USER_OR_GROUP> --key "prop_google_auth" --value "false" UserPropPut ./sacli startEnable TOTP MFA for a specific user or group:
./sacli --user <USER_OR_GROUP> --key "prop_google_auth" --value "true" UserPropPut ./sacli startEnable TOTP MFA for all auto-login profiles:
./sacli --key "vpn.server.google_auth.enable_autologin" --value "true" ConfigPut ./sacli startRemove the setting and restore default behavior:
./sacli --user <USER_OR_GROUP> --key "prop_google_auth" UserPropDel ./sacli startUnlock the user's MFA shared key so the user can enroll on the web interface:
./sacli --user <USER> --lock 0 TotpLock ./sacli startLock the user's MFA shared key so the user cannot obtain/scan it on the web interface:
./sacli --user <USER> --lock 1 TotpLock ./sacli startSee the current MFA shared key for a particular user:
./sacli --pfilt <USER> UserPropGet | grep "pvt_google_auth_secret" ./sacli startCheck 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 startGenerate a new MFA-unlocked shared key so the user can enroll on the web interface:
./sacli --user <USER> --lock 0 TotpRegen ./sacli startGenerate a new MFA-locked shared key so the user can't enroll on the web interface:
./sacli --user <USER> --lock 1 TotpRegen ./sacli start
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.