Set up two-factor authentication (2FA) for SSH access. Google Authenticator PAM module, TOTP setup for SSH, backup codes, testing, and troubleshooting guide.
While using SSH keys improves security, two-factor authentication (2FA) provides an extra security layer. Even if someone obtains your SSH key, they cannot access the system without the 2FA code. This guide walks you through setting up TOTP-based 2FA for SSH using the Google Authenticator PAM module.
Don't close your existing SSH connection during 2FA setup. Test from a new terminal after each step. Incorrect configuration can completely block server access.
# Ubuntu/Debian
sudo apt update
sudo apt install libpam-google-authenticator -y
# CentOS/AlmaLinux
sudo dnf install epel-release -y
sudo dnf install google-authenticator -y
# Run as the user you want to enable 2FA for
google-authenticator
When the command runs, you'll be asked:
Do you want authentication tokens to be time-based (y/n) y
At this point, a QR code and secret key will be displayed. Scan the QR code with the Google Authenticator app.
Do you want me to update your "/home/user/.google_authenticator" file? (y/n) y
Do you want to disallow multiple uses of the same authentication token? (y/n) y
Do you want to increase the window size? (y/n) n
Do you want to enable rate-limiting? (y/n) y
During setup, 5 backup codes are displayed. Store these in a safe place:
Your emergency scratch codes are:
12345678
87654321
11223344
44332211
99887766
Store backup codes in a safe place (password manager, paper, etc.). If you lose your phone, these codes will be your only way in.
# Edit SSH PAM configuration
sudo nano /etc/pam.d/sshd
# Add at the beginning of /etc/pam.d/sshd:
auth required pam_google_authenticator.so
Adding the nullok option allows users without 2FA set up to log in with password only. Useful during transition:
auth required pam_google_authenticator.so nullok
sudo nano /etc/ssh/sshd_config
# Enable keyboard-interactive authentication
ChallengeResponseAuthentication yes
# Set authentication methods
# Option 1: 2FA only (password + TOTP)
AuthenticationMethods keyboard-interactive
# Option 2: SSH key OR 2FA
# AuthenticationMethods publickey keyboard-interactive
# Option 3: SSH key AND 2FA (most secure)
AuthenticationMethods publickey,keyboard-interactive
# UsePAM must be enabled
UsePAM yes
# Restart SSH service
sudo systemctl restart sshd
Most secure configuration: requires SSH key AND 2FA code.
sudo nano /etc/ssh/sshd_config
# SSH key + 2FA required
AuthenticationMethods publickey,keyboard-interactive
PasswordAuthentication no
ChallengeResponseAuthentication yes
UsePAM yes
# PAM configuration
sudo nano /etc/pam.d/sshd
# Comment out password authentication:
# @include common-auth
# Add 2FA
auth required pam_google_authenticator.so
# Open a new terminal and try to connect
ssh user@server_ip
# Expected output:
# Verification code: (enter code from Google Authenticator)
# Authenticated with partial success.
# (in SSH key + 2FA mode)
# Check server time
date
timedatectl
# NTP synchronization
sudo apt install ntp -y
sudo systemctl restart ntp
# Check timezone
timedatectl list-timezones | grep UTC
sudo timedatectl set-timezone UTC
# Connect via console access
# Check Google Authenticator file
cat ~/.google_authenticator
# Temporarily disable 2FA
# Comment out pam_google_authenticator line in /etc/pam.d/sshd
sudo nano /etc/pam.d/sshd
# Add # before: auth required pam_google_authenticator.so
sudo systemctl restart sshd
sudo nano /etc/pam.d/sshd
# Exempt specific groups
auth [success=1 default=ignore] pam_succeed_if.so user ingroup notp
auth required pam_google_authenticator.so
# Create notp group and add user
sudo groupadd notp
sudo usermod -aG notp deploy_user
# Ansible playbook for bulk installation
- name: Install Google Authenticator
hosts: all
tasks:
- name: Install package
apt:
name: libpam-google-authenticator
state: present
- name: PAM configuration
lineinfile:
path: /etc/pam.d/sshd
line: 'auth required pam_google_authenticator.so'
insertbefore: BOF
Apps like Authy or 1Password offer cloud backup and multi-device support compared to Google Authenticator. Consider these alternatives for enterprise environments.
Setting up 2FA for SSH significantly improves server security. With the Google Authenticator PAM module, you can activate TOTP-based 2FA in minutes. The SSH key + 2FA combination forms one of the strongest authentication methods available.
Use the backup codes provided during setup. These codes are single-use. If you've also lost your backup codes, connect to the server via console access and temporarily disable the 2FA line in /etc/pam.d/sshd.
The most common cause is the server and phone clocks being out of sync. Check the time on the server with 'sudo timedatectl' and enable NTP synchronization. Also use the 'Correct time sync' option in the Google Authenticator app.
SSH keys provide strong protection, but 2FA adds an extra security layer. The SSH key + 2FA combination is especially recommended for critical systems or compliance-required environments.
Yes. Any TOTP-supporting app like Authy, Microsoft Authenticator, 1Password, or Bitwarden works. Authy is especially recommended as it offers cloud backup and multi-device support.
It should be mandatory for all users with critical access. SSH keys may be sufficient for service accounts like automated deploy scripts. You can exempt specific groups from 2FA in the PAM configuration.
Protect your Linux server against malware and rootkits. rkhunter and ClamAV installation, scan configuration, result interpretation, scheduled scans, and incident response guide.
Protect your server against SSH brute-force attacks with Fail2Ban. Installation, jail.local configuration, Nginx/Apache jails, IP whitelisting, ban monitoring, and email alerts.
Set up a WireGuard VPN server: key generation, server and client configuration, IP forwarding, firewall rules, and Windows/Linux/Android client setup guide.