For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /general/ssh_security/how_to_set_up_2factor_authentication_for_ssh.md.

How to Set Up Two-Factor Authentication for SSH

Two-factor authentication (2FA) adds an extra layer of security to SSH by requiring a verification code in addition to the configured SSH authentication method.

Warning

Make sure you have an active SSH session or console access before you change authentication settings. An incorrect PAM or SSH configuration can prevent you from logging in. Keep your current SSH session open until you have confirmed that you can log in with the new configuration.

Configure the Server

Install the EPEL repository

Install the Extra Packages for Enterprise Linux (EPEL) repository. When prompted for confirmation, type y and press Enter.

yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

Output:

Running transaction
  Preparing        :                                                        1/1
  Installing       : epel-release-7-12.noarch                               1/1
  Running scriptlet: epel-release-7-12.noarch                               1/1
  Verifying        : epel-release-7-12.noarch                               1/1
Installed:
  epel-release-7-12.noarch
Complete!

Install Google Authenticator

Install the Google Authenticator PAM module. When prompted for confirmation, type y and press Enter.

yum install google-authenticator

Output:

Running transaction
  Preparing        :                                                        1/1
  Installing       : google-authenticator-1.04-1.el7.x86_64                 1/1
  Running scriptlet: google-authenticator-1.04-1.el7.x86_64                 1/1
  Verifying        : google-authenticator-1.04-1.el7.x86_64                 1/1
Installed:
  google-authenticator-1.04-1.el7.x86_64
Complete!

Initialize Google Authenticator

Run the following command:

google-authenticator

The command asks several questions. Answer as shown:

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

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

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

By default, tokens are good for 30 seconds. 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. If you experience problems with
poor time synchronization, you can increase the window from its default
size of +-1min (window size of 3) to about +-4min (window size of 17 acceptable tokens).
Do you want to do so? (y/n) n

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

Save the secret key and scratch codes

The command prints a secret key, a verification code and emergency scratch codes. Save the secret key and the scratch codes securely. You need the secret key to set up the mobile authenticator app, and the scratch codes let you log in if you lose your phone.

Example:

Your new secret key is: LFD2SLJ3R7CPKIC4CJAVMM63OE
Your verification code is 470491
Your emergency scratch codes are:
  86717873
  55870569
  77629708
  22797719
  23075062

The secret key and scratch codes above are examples only. Do not use them on a real server.

Configure the SSH PAM file

Open the SSH PAM configuration file:

nano /etc/pam.d/sshd

Find the following line and comment it out:

auth       substack     password-auth

It should now read:

#auth       substack     password-auth

Add the following lines at the bottom of the file, then save it:

# Used with polkit to reauthorize users in remote sessions
-session   optional     pam_reauthorize.so prepare
auth required pam_google_authenticator.so nullok

Configure OpenSSH

Open the SSH configuration file:

nano /etc/ssh/sshd_config

Find the ChallengeResponseAuthentication setting. Comment out the no setting and enable the yes setting:

# Change to no to disable s/key passwords
ChallengeResponseAuthentication yes
#ChallengeResponseAuthentication no

Add the following lines at the bottom of the file, then save it:

ClientAliveInterval 120
ClientAliveCountMax 2
AuthenticationMethods publickey,password publickey,keyboard-interactive

Restart the SSH service

Restart the SSH service. Keep your current session open.

systemctl restart sshd.service

Set Up the Google Authenticator Mobile App

Install the app

Download Google Authenticator from the Play Store and open it.

Add the account

Select the Add button, then select Enter a provided key.

Enter the key

Enter the account name and the secret key generated during the Google Authenticator setup. Select Time-based, then click Add.

Test the login

Keep your current session open and open a new SSH connection. SSH asks for a verification code. Enter the current code shown in the Google Authenticator app.