How to Set Up MFA for SSH Connections on Linux Servers

Ubuntu / Debian:

sudo apt-get update
sudo apt-get install -y libpam-google-authenticator

RHEL / CentOS / AlmaLinux / Rocky Linux:

sudo dnf install -y epel-release
sudo dnf install -y google-authenticator-libpam

Verify installation:

pamtester sshd $(whoami) open_session  # Should return pamtester: successfully authenticated

Each user who will SSH to the server must run this command as themselves (not as root) to generate their TOTP secret:

google-authenticator

The interactive prompts: answer as follows for a secure default configuration:

Do you want authentication tokens to be time-based? y

# QR code appears here: scan with Google Authenticator, Authy, or any TOTP app

Do you want me to update your ~/.google_authenticator file? y
Do you want to disallow multiple uses of the same authentication token? y
By default, tokens are good for 30 seconds. Do you want to extend it to 4 minutes? n
Do you want to enable rate-limiting? y

The QR code must be scanned before the terminal session ends: it is only displayed once. The wizard also displays emergency scratch codes (one-time backup codes for when the authenticator app is unavailable): store these securely.

The command creates ~/.google_authenticator containing the TOTP secret key and configuration. This file must be readable only by the user:

chmod 600 ~/.google_authenticator

For system administrators setting up MFA for other users: Users must run google-authenticator themselves, or the admin must run it under their account (sudo -u username google-authenticator) and ensure they scan the QR code. The secret cannot be set up without the user's participation.

Edit /etc/pam.d/sshd to require Google Authenticator:

sudo nano /etc/pam.d/sshd

Add this line: the placement matters:

For key + TOTP (most secure: requires both SSH key and TOTP code): Add at the top of the file, before any existing auth lines:

auth required pam_google_authenticator.so

For password + TOTP (if password authentication is enabled): Add after the existing password auth:

auth required pam_google_authenticator.so

To allow users who have not yet set up Google Authenticator to log in (migration period):

auth required pam_google_authenticator.so nullok

The nullok option allows users without a ~/.google_authenticator file to authenticate without TOTP. Remove nullok once all users have enrolled: after that, any user without the file cannot SSH in.

Edit /etc/ssh/sshd_config:

sudo nano /etc/ssh/sshd_config

Required settings for key + TOTP:

# Enable keyboard-interactive authentication (needed for TOTP prompt)
KbdInteractiveAuthentication yes
ChallengeResponseAuthentication yes

# Require BOTH public key AND keyboard-interactive (TOTP)
AuthenticationMethods publickey,keyboard-interactive

# Keep password authentication disabled
PasswordAuthentication no

# Enable PAM (required for Google Authenticator PAM)
UsePAM yes

For password + TOTP (if password login is required):

PasswordAuthentication yes
KbdInteractiveAuthentication yes
AuthenticationMethods keyboard-interactive
UsePAM yes

Restart SSH after changes:

# IMPORTANT: Do not log out of your current session yet
# Open a second SSH connection to verify before closing the first
sudo systemctl restart sshd

Verify in a new terminal window: test the new configuration before closing your existing session. If something is misconfigured, your existing session remains open to fix it.

Test from a new SSH session:

ssh -v user@server.example.com

The expected authentication flow for key + TOTP:

1. SSH key authentication completes silently
2. A prompt appears: Verification code:: enter the 6-digit TOTP code from the authenticator app
3. Session opens

Common issues:

Issue: TOTP prompt does not appear (goes straight to key-only login) Cause: AuthenticationMethods is not set correctly, or UsePAM yes is missing Fix: Verify both settings in sshd_config and restart sshd

Issue: Permission denied even with correct TOTP code Cause: Clock skew: TOTP codes are time-based and require the server and authenticator device to have synchronized clocks. A difference of more than 90 seconds causes code rejection. Fix: sudo timedatectl set-ntp true and verify NTP is syncing: timedatectl status

Issue: Users locked out after setup Cause: nullok not set during migration, user has not run google-authenticator yet Fix: Temporarily add nullok to the PAM line, allow the user to run google-authenticator, then remove nullok

Exempting specific accounts from MFA (service accounts):

# In /etc/pam.d/sshd: use pam_succeed_if to skip MFA for specific users
auth [success=1 default=ignore] pam_succeed_if.so user ingroup nomfa
auth required pam_google_authenticator.so

Create a nomfa group and add service accounts to it: they authenticate with key only. All other users require key + TOTP.