Two-Factor Authentication (2FA) via Google Authenticator on Ubuntu Server

Procedure for adding two-factor authentication (2FA) to a server using Google Authenticator. 2FA is a method of securing server access (typically through SSH and local access) by combining a user password with a one-time password (OTP), which is generated by the Google Authenticator app on the user's mobile device. This process adds an additional layer of security to the authentication mechanism, as an attacker would need to know the password and have the current OTP to successfully log in.

Vladimír NeporAuthorVladimír Nepor
PublishedUpdated

Procedure for Adding and Activating 2FA via Google Authenticator on Ubuntu Server

  1. Install the "Google Authenticator" app from Google on your mobile phone. The app is available for both iOS and Android.
  2. On the server, install the Google Authenticator package
    sudo apt install -y libpam-google-authenticator

  3. Depending on where we want to apply the 2FA requirement during login, we determine the PAM (pluggable authentication modules) configuration file into which the entry auth required pam_google_authenticator.so is inserted, see the options below:

    • Open the PAM configuration file common-auth
      sudo nano /etc/pam.d/common-auth

      The record auth required pam_google_authenticator.so must be inserted into the configuration file. The position of insertion affects the order in which 2FA authorization is required.

      • If inserted at the beginning, as shown below, the 2FA code is required before the password.
        ...
# pam-auth-update to manage selection of other modules.  See
# pam-auth-update(8) for details.

# Enable Google Authenticator   <-- inserted entry
auth required pam_google_authenticator.so

# here are the per-package modules (the "Primary" block)
...
      • If inserted at the end of the file, 2FA will be required after entering the password.
    • Save and close the file with the keyboard shortcut CTRL+X, then Y and ENTER.

    Note: With the common-auth variant, 2FA applies to all users and to sudo commands as well. With the SSH-only variant, it applies only to SSH logins.

  4. Open the configuration file sshd_config
    sudo nano /etc/ssh/sshd_config
    • Ensure that KbdInteractiveAuthentication is set to yes
    • Set the record:
      AuthenticationMethods keyboard-interactive:pam

      If public key is also activated, its requirement can be specified by the record:

      AuthenticationMethods publickey,keyboard-interactive:pam

      In sshd the first value found wins: if the file (or /etc/ssh/sshd_config.d/) already contains e.g. AuthenticationMethods publickey or KbdInteractiveAuthentication no from the SSH keys guide, edit those records instead of adding new ones. Put the record before any Match block. Verify the result with sudo sshd -T | grep -Ei '^(kbdinteractiveauthentication|authenticationmethods)'.

    • Save and close the file with the keyboard shortcut CTRL+X, then Y and ENTER.
  5. On the server, invoke the command google-authenticator and choose the option y for "time based tokens".
  6. Open the Google Authenticator app on your mobile phone and with the "+ (Add) → scan QR code" option, link your phone to the server.
  7. The QR code is defined by a security key (secret key), which is displayed under the said QR code. Write down this code.
  8. As prompted, type the code displayed in the Google Authenticator app into the terminal.
  9. Carefully keep the displayed five eight-digit backup codes along with the secret key (2 points above) for possible use in case of phone loss.
  10. When prompted about updating the file ~/.google_authenticator, respond with y
  11. When prompted about the prohibition of reuse of codes, respond with y
  12. When prompted about time skew, respond with n
  13. When prompted about rate-limiting, respond with y
  14. Restart ssh(d) service
    sudo systemctl restart ssh
  15. 2FA is now activated for logging in (and, with the common-auth variant, for sudo commands).
  16. If there are multiple regular users on the server, a 2FA authentication setup via google-authenticator must be performed individually for each user. Each user always has their own 2FA codes.
    • Switch to a specific user: $ sudo su - someuser
    • Start the 2FA configuration for a user: $ google-authenticator
    • Return to the original user: $ exit

Need a secure server setup?

We design, secure and document networks and servers.

Servers & Networks