How to set up OTP 2FA for SSH authentication

OTP (One-time password) with a soft token is one of the most widely-used 2FA (Two-factor authentication) or MFA (Multi-factor authentication) methods.

openSSH server supports two-factor authentication using OTP via libpam-google-authenticator module for PAM (Pluggable Authentication Modules). Both SSH and PAM need to be configured on the server to enable this authentication method.

Google Authenticator, Authy, or any other soft token application that generates time-dependent codes could then be used on the client-side to authenticate.

1. Launch terminal.
2. Install libpam-google-authenticator.

   $ sudo apt update && sudo apt install --assume-yes libpam-google-authenticator # Ubuntu and Debian variance

3. Open SSHd configuration file using your preferred text editor.

   $ sudo vi /etc/ssh/sshd_config

4. Set ChallengeResponseAuthentication directive to yes.

   ChallengeResponseAuthentication yes

   Remove leading # if exist to uncomment the line.

5. Set keyboard-interactive authentication method for the user.

   Match User username
       AuthenticationMethods keyboard-interactive

   This is optional as keyboard-interactive is by default enabled for all users.

   Set other authentication method for the specific user to exclude them from using OTP 2FA. Possible authentication methods:

   gssapi-with-mic,hostbased,publickey, password

   Related: How to set the preferred authentication method for SSH

6. Save and exit text editor.
7. Restart SSH service.

   $ sudo systemctl restart ssh

   Related: How to start, restart, and stop the SSH server service

8. Open sshd configuration for PAM using your preferred text editor.

   $ sudo vi /etc/pam.d/sshd

9. Add the following lines at the end of file.

   auth    required      pam_unix.so     no_warn try_first_pass
   auth    required      pam_google_authenticator.so

   This will require the use of password first to log in, followed by the Google Authenticator module.

10. Save and exit the editor.
11. Run google-authenticator command to start configuring and generating the QR code for the user.

    $ google-authenticator

    This step need to be repeated for all other users.

12. Type y and press [ENTER] to use time-based authentication token.

    Do you want authentication tokens to be time-based (y/n) y

13. Scan generated QR code using Google Authenticator, Authy or any other similar app.
14. Enter code generated from the app and press [ENTER].

    Enter code from app (-1 to skip): 466822
    Code confirmed
    Your emergency scratch codes are:
      21277551
      15985104
      82336172
      67376642
      85166830

15. Type y and press [ENTER] to confirm generation of configuration file for the google authenticator module.

    Do you want me to update your "/home/user/.google_authenticator" file? (y/n) y

16. Type y and press [ENTER] to force only a single use of generated time-based token.

    Do you want to disallow multiple uses of the same authentication
    token? This restricts you to one login about every 30s, but it increases
    your chances to notice or even prevent man-in-the-middle attacks (y/n) y

    Set this to n to allow multiple use of the same code.

17. Type y and press [ENTER] to agree to code generation and usage policies.

    By default, a new token is generated every 30 seconds by the mobile app.
    In order to compensate for possible time-skew between the client and the server,
    we allow an extra token before and after the current time. This allows for a
    time skew of up to 30 seconds between authentication server and client. If you
    experience problems with poor time synchronization, you can increase the window
    from its default size of 3 permitted codes (one previous code, the current
    code, the next code) to 17 permitted codes (the 8 previous codes, the current
    code, and the 8 next codes). This will permit for a time skew of up to 4 minutes
    between client and server.
    Do you want to do so? (y/n) y

18. Type y and press [ENTER] to enable rate-limiting option.

    If the computer that you are logging into isn't hardened against brute-force
    login attempts, you can enable rate-limiting for the authentication module.
    By default, this limits attackers to no more than 3 login attempts every 30s.
    Do you want to enable rate-limiting? (y/n) y