Skip to main content

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

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 OTP, etc. There are also standalone hardware devices that support this and work with Access Server, such as the Protectimus Slim NFC token.

Step 1: Connect to the console

  1. Sign in to your Access Server system using a terminal or console session. Examples:

    • Open a terminal windows (Linux or macOS).

    • Use PuTTY or another SSH client on Windows.

    • Use Ubuntu on Windows (WSL).

    • Access the server directly through a virtual machine or cloud provider terminal.

  2. Once connected, get root privileges. Example:

    sudo -s

    Note

    All commands in this tutorial assume you have root access.

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

The TotpLock and TotpRegen functions manage these two keys:

  1. pvt_google_auth_secret — A 16-character alphanumerical value containing the MFA shared key.

  2. 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: