Skip to content

Two-Factor SSH with TOTP: pam_google_authenticator Setup

Add TOTP codes to SSH with pam_google_authenticator: key plus code via AuthenticationMethods, PAM edits for Debian and RHEL, automation exemptions, and lockout recovery.

●By 11 min read

Key-only SSH is a strong baseline, and our SSH security best practices guide covers getting there. But a private key is still a single file. Copied off a laptop backup, lifted from a compromised workstation, or left in a CI variable, it grants exactly the same access as it does to you. A time-based one-time password (TOTP) adds a second factor that lives on a different device.

The pam_google_authenticator module implements RFC 6238 TOTP inside PAM, so it works with any authenticator app and no external service. The module itself is the easy part. The tricky part is the interaction between sshd_config and the PAM stack, which decides whether users get key plus code, password plus code, or, if you get it wrong, the key alone with no code at all.

Install the Module and Enroll a User

The package name differs by distro. On RHEL, Rocky and AlmaLinux it comes from EPEL. Install qrencode too if you want the enrollment QR code drawn in the terminal.

# Debian / Ubuntu

$ sudo apt install libpam-google-authenticator qrencode

# RHEL / Rocky / AlmaLinux (enable EPEL first)

$ sudo dnf install epel-release

$ sudo dnf install google-authenticator qrencode

# Fedora

$ sudo dnf install google-authenticator qrencode

Each user enrolls as themselves, not as root, because the tool writes the secret to the home directory of whoever runs it. The interactive version asks five questions; the flags below answer them up front:

$ google-authenticator -t -d -f -r 3 -R 30 -w 3

# prints a QR code, then:

Your new secret key is: JBSWY3DPEHPK3PXPJBSWY3DPEH

Enter code from app (-1 to skip): 482913

Code confirmed

Your emergency scratch codes are:

71236409

30981527

...

$ ls -l ~/.google_authenticator

-r-------- 1 alice alice 147 Oct 2 10:14 /home/alice/.google_authenticator

FlagMeaningWhy you want it
-tTime-based codes (TOTP)Counter-based HOTP codes drift out of sync; TOTP does not
-dDisallow reuse of a codeA code captured by a shoulder-surfer or keylogger cannot be replayed within its 30 seconds
-fWrite the file without askingNeeded for scripted enrollment
-r 3 -R 30At most 3 logins per 30 secondsSlows brute force against the 6-digit code
-w 3Accept the previous, current and next codeTolerates about 30 seconds of clock skew in either direction

Scratch codes are single use β€” each one works once, then the module deletes it from the file. Store them in a password manager, not in the same place as the private key.

The file is the secret β€” anyone who can read ~/.google_authenticator can generate valid codes. The module refuses to use it if it is readable by others, so leave the mode at 0400 or 0600.

Clock sync is mandatory β€” TOTP compares the server clock to the phone clock. Check that timedatectl reports System clock synchronized: yes before you enforce codes, or a drifting VM will lock everyone out.

How sshd and PAM Decide What Gets Asked

This is the section to read twice. sshd has several authentication methods. publickey is handled by sshd itself, while keyboard-interactive hands the conversation to PAM, which runs every auth line in /etc/pam.d/sshd. The AuthenticationMethods directive says which methods must all succeed, in order. The combination determines what the user sees:

AuthenticationMethodsPAM password includeUser is asked for
not setanyKey alone is enough. TOTP is never asked when the key works.
publickey,keyboard-interactiveremovedKey, then verification code
publickey,keyboard-interactivekeptKey, then password, then verification code
keyboard-interactivekeptPassword, then verification code (no key)

The first row is the trap. Adding the module to PAM without setting AuthenticationMethods looks like it works when you test with a password, but every user who logs in with a key skips the second factor entirely.

Configure Key Plus Code

The most common target is a key and a code with no password, since users on key-only servers often have no password set. First, edit the PAM stack. Add the module and stop PAM from also asking for the Unix password:

# /etc/pam.d/sshd on Debian / Ubuntu

# @include common-auth <- comment this out: it asks for the password

auth required pam_google_authenticator.so nullok

# /etc/pam.d/sshd on RHEL / Rocky / Fedora

#auth substack password-auth <- comment this out

auth required pam_google_authenticator.so nullok

Leave the account, session and password lines alone; only the auth password include goes. Then set sshd's side. A drop-in file keeps your change separate from the distro default:

# /etc/ssh/sshd_config.d/10-mfa.conf

UsePAM yes

KbdInteractiveAuthentication yes

AuthenticationMethods publickey,keyboard-interactive

$ sudo sshd -t # syntax check, prints nothing on success

$ sudo sshd -T | grep -Ei 'kbdinteractive|authenticationmethods|usepam'

usepam yes

kbdinteractiveauthentication yes

authenticationmethods publickey,keyboard-interactive

$ sudo systemctl reload ssh # Debian / Ubuntu

$ sudo systemctl reload sshd # RHEL / Fedora

First value wins β€” sshd uses the first value it reads for most directives, and the main sshd_config includes sshd_config.d/*.conf near the top. A file named 10-mfa.conf is read before 50-cloud-init.conf, so it wins. Always confirm the effective value with sshd -T.

Old directive name β€” KbdInteractiveAuthentication replaced ChallengeResponseAuthentication in OpenSSH 8.7. The old name still works as an alias, but Ubuntu 22.04 and later ship with the new one set to no, which silently disables the PAM conversation.

nullok during rollout β€” with nullok, users who have not enrolled yet log in with the key alone. Remove it once everyone has a .google_authenticator file, or the second factor stays optional forever.

Keep a session open β€” reload, then test from a second terminal while the first stays logged in. A broken PAM line can lock out every new login, including yours.

A successful login with ssh -v shows both steps. The key is accepted but marked as a partial success, and then PAM prompts for the code:

$ ssh -v alice@web01

...

debug1: Server accepts key: /home/alice/.ssh/id_ed25519 ED25519 SHA256:...

Authenticated using "publickey" with partial success.

debug1: Authentications that can continue: keyboard-interactive

debug1: Next authentication method: keyboard-interactive

(alice@web01) Verification code:

sponsored

Exemptions for Automation and Trusted Networks

Backup jobs, Ansible runs and CI deploy keys cannot type a code. Rather than leaving nullok in place for them, give them an explicit exemption in sshd with a Match block. AuthenticationMethods is allowed inside Match, and the block must come after the global settings:

# /etc/ssh/sshd_config.d/10-mfa.conf (continued)

Match Group automation

AuthenticationMethods publickey

Match Address 10.20.0.0/24

AuthenticationMethods publickey

Exempt by group, not by user β€” a Unix group such as automation makes the exemption list auditable with getent group automation, and new service accounts inherit it.

Restrict exempted keys β€” a key that skips 2FA should be able to do only one thing. Combine the exemption with a forced command and restrict in authorized_keys, so a stolen backup key cannot open a shell.

Address exemptions trust the network β€” exempting a management subnet means anyone who reaches that subnet skips the code. That is reasonable behind a VPN that itself requires MFA, and risky on a flat office LAN.

Do not exempt root β€” if root can log in over SSH at all, it should be the account with the strongest requirements, not the weakest.

SELinux, Encrypted Homes and Other Failure Modes

Most broken setups fail in one of a handful of ways. The log tells you which: journalctl -u ssh on Debian and Ubuntu, journalctl -u sshd or /var/log/secure on RHEL.

SymptomLikely causeFix
Key accepted, no code promptAuthenticationMethods not set, or not in effectCheck sshd -T output, not the file
Code prompt never appears, login failsKbdInteractiveAuthentication noSet it to yes in a drop-in that is read first
Password asked before the codePAM password include still activeComment out common-auth / password-auth in /etc/pam.d/sshd
Valid codes rejectedClock drift, or code already used with -dFix time sync; wait for the next code
Valid codes fail on RHEL, AVCs in the audit logSecret file has the wrong SELinux labelCheck ausearch -m avc -ts recent; restorecon the file
Fails only for some usersHome directory not mounted until after loginStore secrets outside home with secret= and user=

The module rewrites the secret file on every login to record used codes and rate-limit state, so sshd needs write access to it. On SELinux systems the policy expects a specific label on ~/.google_authenticator. A file that was copied or moved into place keeps the label of where it came from, and the denial shows up as an AVC for sshd_t. Resetting the label to the policy default fixes it:

$ sudo ausearch -m avc -ts recent | grep -i google

$ restorecon -v ~/.google_authenticator

Encrypted or network-mounted home directories are a different problem: the file is not there until after login. The fix is a central directory owned by root, with the module told where to look:

$ sudo mkdir -m 700 /var/lib/google-authenticator

# enroll a user into the central location

$ sudo google-authenticator -t -d -f -r 3 -R 30 -w 3 \

-s /var/lib/google-authenticator/alice

# /etc/pam.d/sshd

auth required pam_google_authenticator.so secret=/var/lib/google-authenticator/${USER} user=root

The ${USER} placeholder is expanded by the module itself, not by a shell, and user=root tells it which account owns the files. Users can no longer read their own secret, which also means only an admin can re-enroll them. On SELinux systems, test a login right after the move: a directory under /var/lib gets a different label from a home directory, and if ausearch shows denials, add a file context rule with semanage fcontext rather than switching SELinux to permissive.

Recovery and Lockout Planning

Phones get lost and wiped. Plan the recovery path before you remove nullok, not after the first support call.

Scratch codes first β€” a user with a saved scratch code logs in normally, then runs google-authenticator again to enroll a new phone, which invalidates the old secret.

Admin re-enrollment β€” an admin can move the user's secret file aside, temporarily add the user to the exempt group, and let them enroll again. Log who did it and why.

Console access is the last resort β€” cloud serial consoles and hypervisor consoles go through login, not sshd, so they are unaffected by the sshd PAM file. Confirm you can actually reach one before enforcing 2FA on a remote fleet.

Test with a config management run β€” if you roll this out with Ansible or similar, make sure the automation account is exempt before the play that removes nullok, or the second half of the play cannot connect.

Consider hardware keys too β€” FIDO2 keys (ssh-keygen -t ed25519-sk) put the second factor in the key itself and resist phishing better than six digits. TOTP is the option that works with any phone and any client.

Frequently Asked Questions

Why does SSH not ask for my TOTP code when I log in with a key?

Because without AuthenticationMethods, a successful public key login is sufficient and sshd never runs the PAM auth stack. Set AuthenticationMethods publickey,keyboard-interactive and confirm it with sudo sshd -T. Also check that KbdInteractiveAuthentication is yes in the effective configuration.

How do I require a key and a code but no password?

Set AuthenticationMethods publickey,keyboard-interactive in sshd, then remove the password step from PAM by commenting out @include common-auth in /etc/pam.d/sshd on Debian and Ubuntu, or the auth substack password-auth line on RHEL and Fedora. Add auth required pam_google_authenticator.so in its place.

What does the nullok option do in pam_google_authenticator?

It lets users who have no secret file log in without a code. It is useful while users are enrolling, but it makes the second factor optional, so remove it once everyone is enrolled and handle automation accounts with an explicit Match exemption instead.

Do I need internet access on the server for TOTP?

No. TOTP codes are computed from a shared secret and the current time, so the server never contacts Google or any other service. It does need an accurate clock, so keep NTP or chrony running and check timedatectl.

How do I exempt backup or CI accounts from SSH 2FA?

Put the accounts in a group and add a Match Group block after the global settings with AuthenticationMethods publickey. Restrict those keys in authorized_keys with a forced command and the restrict option so an exempted key can do only its one job.

sponsored

Related Tools

See also