Configure SSH to use two-factor authentication

SSH, the secure shell, is often used to access remote Linux systems. Because we often use it to connect with computers containing important data, it’s recommended to add another security layer, such as two factor authentication (2FA).

Before you start

What is two-factor authentication?

Multi-factor authentication is a method of confirming your identity using at least two different ways of authentication. The most common and easiest to implement example of two-factor authentication uses a combination of passphrase (a complex password, often made of several words) and a one-time-passcode generated by a special mobile app.

We will use the Google Authenticator app available for Android and iOS to generate authentication codes.

Prerequisites

• A computer running Ubuntu 16.04 LTS or later.
• A phone running Android or iOS.
• A configured SSH connection.
• You should understand the danger of stolen passwords.
• You don’t need to know what two-factor authentication is and how it works.

Install the required packages on Ubuntu

Run the following commands in a terminal session.

Make sure the SSH server is installed

sudo apt install openssh-server

Install the Google Authenticator PAM module

sudo apt install libpam-google-authenticator

Configure SSH

To make SSH use the Google Authenticator PAM module, add the following line to the /etc/pam.d/sshd file:

auth required pam_google_authenticator.so

Ubuntu 22.04 and laterUbuntu 16.04 to 20.04

Create the /etc/ssh/sshd_config.d/99-mfa.conf file. In it, set the KbdInteractiveAuthentication option to yes:

# Change to "yes" to enable keyboard-interactive authentication.  Depending on
# the system's configuration, this may involve passwords, challenge-response,
# one-time passwords or some combination of these and other methods.
# Beware issues with some PAM modules and threads.
KbdInteractiveAuthentication yes

Edit the /etc/ssh/sshd_config file. Change the ChallengeResponseAuthentication option from no to yes, so this part of the file looks like:

# Change to yes to enable challenge-response passwords (beware issues with
# some PAM modules and threads)
ChallengeResponseAuthentication yes

# Change to no to disable tunnelled clear text passwords
#PasswordAuthentication yes

Allow password or SSH key

In some scenarios, you authenticate using an SSH key instead of a password. For example, with Ubuntu on cloud instances, an SSH key is set by default, which is considered as sufficient authentication by SSH, and you aren't prompted for your one-time passcode.

To require that a password or an SSH key must always be followed by your one-time passcode, add the following configuration in the /etc/ssh/sshd_config.d/99-mfa.conf or /etc/ssh/sshd_config file:

PubkeyAuthentication yes
KbdInteractiveAuthentication yes
UsePAM yes
AuthenticationMethods publickey,keyboard-interactive:pam keyboard-interactive:pam

Warning
With this configuration, you can't connect using a password and 2FA. The SSH key is always required.

Apply the changes

Restart the ssh service to reload the configuration:

sudo systemctl restart ssh.service

Configure authentication on Ubuntu

Google Authenticator makes the configuration of two-factor authentication much easier, comparing to (for example) libpam-oath.

In a terminal, run the following command:

google-authenticator

It will ask you a series of questions. Here is a recommended configuration:

Question	Recommended answer
Make tokens “time-base”	yes
Update the .google_authenticator file	yes
Disallow multiple uses	yes
Increase the original generation time limit	no
Enable rate-limiting	yes

You may notice the giant QR code that appears during the process. Underneath are your emergency scratch codes, to be used if you don’t have access to your phone. Write them down on paper and keep them in a safe place.

Note
Don’t use unencrypted services to store secret keys, such as a notes synchronization service and so on. If you don’t want to type the key manually, use the QR code.

Add the secret to Google Authenticator on your phone

Install Google Authenticator:

• On Android, go to the Play Store.
• On iOS, go to iTunes.

Now, let’s open Google Authenticator and add our secret key to make it work.

In this example, we will use the latest version of Authenticator from the Play Store. The process shouldn’t look very different on iOS.

Using the QR code

Touch the Add icon (+) and select Scan a barcode. Use phone camera to scan QR code from Ubuntu.

Using the through key

Touch the Add icon (+) and select Enter a provided key.

Enter a name that you will recognize as being your 2FA method for SSH.

Type the secret key provided by google-authenticator command.

Done

Congratulations! You have just configured two-factor authentication for SSH shell using Google Authenticator. Now, every time you (or some bad guy with your password…) will try to log in to your SSH shell, you (or this bad guy) will be asked for an authentication key in addition to a traditional passphrase.

Copy the code from the Google Authenticator app on your phone.