> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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**.
```bash
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**.
```bash
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:
```bash
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:
```bash
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:
```bash
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.
```bash
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.
