# How to Enable Google Authenticator for SSH 2FA on Linux

> Secure Linux SSH with Google Authenticator. Easily enable SSH 2FA by installing the PAM module, generating secrets, and configuring PAM and SSHD for TOTP security.

- Repository: [IMTheNachoMan/How-To-Secure-A-Linux-Server](https://github.com/imthenachoman/How-To-Secure-A-Linux-Server)
- Tags: how-to-guide
- Published: 2026-05-14

---

**Install the `libpam-google-authenticator` package, run `google-authenticator` to generate per-user secrets, add `auth required pam_google_authenticator.so nullok` to `/etc/pam.d/sshd`, and enable `ChallengeResponseAuthentication` in `/etc/ssh/sshd_config` to enforce TOTP-based two-factor authentication for all SSH logins.**

Securing SSH access with two-factor authentication (2FA) adds a critical defense layer against credential theft and brute-force attacks. The open-source repository *imthenachoman/How-To-Secure-A-Linux-Server* provides a complete, production-ready guide to enable Google Authenticator for SSH 2FA using standard Linux PAM modules without modifying system binaries.


## Architecture and Authentication Flow

The solution implements a **two-factor login flow** by chaining three standard Linux components:

```

user → sshd → PAM → (password verification) → PAM → (Google Authenticator token) → login granted

```

**PAM (Pluggable Authentication Modules)** handles the authentication sequence for the SSH service. By adding `pam_google_authenticator.so` to `/etc/pam.d/sshd`, PAM invokes the Google Authenticator module immediately after password verification succeeds.

**Google Authenticator Library** stores a unique secret key in `~/.google_authenticator` for each user and validates the six-digit time-based one-time passwords (TOTP) generated by the user's authenticator app.

**SSH Daemon (`sshd`)** forwards authentication requests to PAM when `ChallengeResponseAuthentication` is enabled, triggering the sequential password-and-token prompts.


## Step-by-Step Implementation

Execute these commands exactly as documented in the repository's **"2FA/MFA for SSH"** section.

### Install the PAM Module

First, install the `libpam-google-authenticator` package using your distribution's package manager:

```bash
sudo apt install libpam-google-authenticator

```

### Generate User Secrets

Run the interactive setup utility as the target user (not root) to generate the secret key and QR code:

```bash
google-authenticator

```

Follow the prompts to enable time-based tokens, save the emergency scratch codes, and configure rate-limiting options. This creates the secret file at `~/.google_authenticator`.

### Backup and Configure SSH PAM

Create a backup of your existing PAM configuration, then append the Google Authenticator module:

```bash
sudo cp /etc/pam.d/sshd /etc/pam.d/sshd.bak
echo "auth required pam_google_authenticator.so nullok" | sudo tee -a /etc/pam.d/sshd

```

The `nullok` argument allows users who have not yet configured Google Authenticator to log in with just their password, enabling a gradual rollout.

### Enable Challenge-Response Authentication

Modify `/etc/ssh/sshd_config` to permit the interactive token prompt:

```bash
sudo sed -i 's/^#\?ChallengeResponseAuthentication.*/ChallengeResponseAuthentication yes/' /etc/ssh/sshd_config

```

### Apply Configuration Changes

Restart the SSH service to load the new PAM stack and daemon settings:

```bash
sudo service sshd restart

```


## Important Configuration Details

### Secret Storage Location

Each user's TOTP secret and configuration reside in `~/.google_authenticator`. Protect this file with strict permissions (typically `0600`) to prevent unauthorized access to the seed material.

### The nullok Flag

According to the *How-To-Secure-A-Linux-Server* source, the `nullok` parameter in `/etc/pam.d/sshd` ensures compatibility during migration. Remove this flag after all users have enrolled to enforce mandatory 2FA for every account.

### SSH Key Authentication Interaction

When users authenticate with SSH public keys, the authentication flow bypasses PAM password checks by default. To require both SSH keys and a TOTP token, additional configuration changes are required beyond the basic setup documented here.


## Summary

- **Install** the `libpam-google-authenticator` package to add TOTP support to the system's PAM stack.
- **Generate secrets** by running `google-authenticator` as each individual user to create the `~/.google_authenticator` file.
- **Configure PAM** by adding `auth required pam_google_authenticator.so nullok` to `/etc/pam.d/sshd` to trigger token validation after password verification.
- **Enable challenge-response** in `/etc/ssh/sshd_config` by setting `ChallengeResponseAuthentication yes`.
- **Restart `sshd`** to apply changes, enforcing two-factor authentication for password-based logins.


## Frequently Asked Questions

### Does enabling Google Authenticator affect SSH key-based authentication?

Standard configuration changes only affect password authentication. SSH key logins bypass the PAM password stack by default, so they will not prompt for a TOTP token unless you explicitly configure `sshd` to require PAM for key authentication or implement additional forced commands.

### What happens if I lose my phone or authenticator app access?

During the `google-authenticator` setup, the utility generates emergency **scratch codes**. Store these single-use backup codes securely; they allow authentication without the TOTP generator to prevent lockout.

### Is the `nullok` option secure for production use?

The `nullok` flag in `/etc/pam.d/sshd` permits login without a token for users lacking a `~/.google_authenticator` file. This facilitates staged rollouts but should be removed (`nullok` deleted) once all users have enrolled, ensuring universal 2FA enforcement.

### Which Linux distributions support this implementation?

This method works on any distribution shipping the `libpam-google-authenticator` package, including Debian, Ubuntu, RHEL, CentOS, and Fedora. The PAM configuration syntax in `/etc/pam.d/sshd` is standardized across Linux PAM implementations.