Securing SSH with Google Authenticator: Two-Factor Authentication Setup

Table of Contents#

Overview#

Securing SSH access is crucial for protecting servers from unauthorized access. This guide demonstrates how to implement two-factor authentication (2FA) using Google Authenticator, adding an extra layer of security beyond traditional password or key-based authentication.

Security Architecture#

graph TB
    subgraph "Authentication Flow"
        A[SSH Client] --> B[SSH Server]
        B --> C{Auth Method}
        C --> D[Password/Key]
        D --> E{Valid?}
        E -->|Yes| F[PAM Module]
        E -->|No| G[Reject]
        F --> H[Google Auth]
        H --> I{TOTP Valid?}
        I -->|Yes| J[Grant Access]
        I -->|No| K[Reject]
    end

    subgraph "Components"
        L[Google Authenticator App]
        M[PAM Module]
        N[SSH Configuration]
        O[User Secret Keys]
    end

    L --> H
    M --> F
    N --> B
    O --> H

    style A fill:#4ecdc4,stroke:#087f5b,stroke-width:2px
    style J fill:#51cf66,stroke:#2f9e44,stroke-width:2px
    style G fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px
    style K fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px

Prerequisites#

System Requirements#

1
# Check system information
2
cat /etc/os-release
3
uname -a
4

5
# Ensure SSH is installed
6
ssh -V
7

8
# Check PAM version
9
rpm -qa | grep pam  # RHEL/CentOS
10
dpkg -l | grep libpam  # Debian/Ubuntu

Time Synchronization#

1
# Install NTP client
2
sudo apt install ntp  # Debian/Ubuntu
3
sudo yum install ntp  # RHEL/CentOS
4

5
# Sync time
6
sudo ntpdate -s time.nist.gov
7

8
# Enable NTP service
9
sudo systemctl enable ntp
10
sudo systemctl start ntp
11

12
# Verify time
13
date
14
timedatectl status

Installation#

Installing Google Authenticator#

1
# Debian/Ubuntu
2
sudo apt update
3
sudo apt install libpam-google-authenticator
4

5
# RHEL/CentOS/Fedora
6
sudo yum install epel-release
7
sudo yum install google-authenticator
8

9
# From source (if packages unavailable)
10
git clone https://github.com/google/google-authenticator-libpam.git
11
cd google-authenticator-libpam
12
./bootstrap.sh
13
./configure
14
make
15
sudo make install

Verify Installation#

1
# Check PAM module
2
ls -la /lib/x86_64-linux-gnu/security/pam_google_authenticator.so
3
# or
4
ls -la /lib64/security/pam_google_authenticator.so
5

6
# Test command availability
7
which google-authenticator

User Configuration#

Generate Secret Key#

1
# Run as the user (not root)
2
google-authenticator
3

4
# Interactive prompts:
5
# Do you want authentication tokens to be time-based? yes
6
# Do you want me to update your ~/.google_authenticator file? yes
7
# Do you want to disallow multiple uses? yes
8
# Increase time window? no
9
# Enable rate-limiting? yes

Configuration Options#

graph TD
    A[Google Authenticator Setup] --> B[Time-based tokens]
    A --> C[Counter-based tokens]

    B --> D[30-second window]
    B --> E[QR Code generation]
    B --> F[Emergency codes]

    C --> G[HOTP mode]

    D --> H[Clock sync critical]
    E --> I[Mobile app scan]
    F --> J[Backup access]

    style A fill:#4ecdc4,stroke:#087f5b,stroke-width:2px
    style B fill:#74c0fc,stroke:#1971c2,stroke-width:2px
    style F fill:#ffd43b,stroke:#fab005,stroke-width:2px

Non-Interactive Setup#

1
#!/bin/bash
2
# generate-2fa.sh - Non-interactive 2FA setup
3

4
# Generate secret for a user
5
generate_2fa_secret() {
6
    local user=$1
7

8
    # Generate with specific options
9
    su - $user -c "google-authenticator \
10
        --time-based \
11
        --disallow-reuse \
12
        --force \
13
        --rate-limit=3 \
14
        --rate-time=30 \
15
        --window-size=3 \
16
        --secret=/home/$user/.google_authenticator"
17

18
    # Display QR code
19
    su - $user -c "google-authenticator \
20
        --time-based \
21
        --qr-mode=utf8"
22
}
23

24
# Usage
25
generate_2fa_secret "username"

PAM Configuration#

Configure PAM for SSH#

Edit /etc/pam.d/sshd:

1
# Backup original file
2
sudo cp /etc/pam.d/sshd /etc/pam.d/sshd.backup
3

4
# Edit PAM configuration
5
sudo nano /etc/pam.d/sshd

Add the following line:

1
# For required 2FA (must pass)
2
auth required pam_google_authenticator.so
3

4
# For optional 2FA (can bypass if not configured)
5
auth required pam_google_authenticator.so nullok
6

7
# With custom options
8
auth required pam_google_authenticator.so nullok grace_period=30 debug

PAM Configuration Examples#

1
# Standard configuration (password + 2FA)
2
@include common-auth
3
auth required pam_google_authenticator.so
4

5
# Public key + 2FA only
6
#@include common-auth
7
auth required pam_google_authenticator.so

Advanced PAM Options#

1
# Full options example
2
auth required pam_google_authenticator.so \
3
    secret=/home/${USER}/.google_authenticator \
4
    user=root \
5
    forward_pass \
6
    debug \
7
    authtok_prompt="Verification code: " \
8
    nullok \
9
    grace_period=30

SSH Configuration#

Enable Challenge-Response#

Edit /etc/ssh/sshd_config:

1
# Backup SSH config
2
sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.backup
3

4
# Edit configuration
5
sudo nano /etc/ssh/sshd_config

Required settings:

1
# Enable challenge-response authentication
2
ChallengeResponseAuthentication yes
3

4
# For public key + 2FA
5
AuthenticationMethods publickey,keyboard-interactive
6

7
# For password + 2FA
8
AuthenticationMethods password,keyboard-interactive
9

10
# Or allow either method + 2FA
11
AuthenticationMethods publickey,keyboard-interactive password,keyboard-interactive
12

13
# Ensure PAM is enabled
14
UsePAM yes
15

16
# Optional: Disable password-only auth
17
PasswordAuthentication no

Per-User Configuration#

1
# Match specific users for 2FA
2
Match User admin,root
3
    AuthenticationMethods publickey,keyboard-interactive
4

5
Match Group sudo
6
    AuthenticationMethods publickey,keyboard-interactive
7

8
Match User serviceaccount
9
    AuthenticationMethods publickey

Restart SSH Service#

1
# Test configuration
2
sudo sshd -t
3

4
# Restart SSH service
5
sudo systemctl restart sshd
6

7
# Monitor logs
8
sudo journalctl -fu sshd

Testing and Verification#

Test Authentication Flow#

sequenceDiagram
    participant U as User
    participant S as SSH Client
    participant D as SSH Server
    participant P as PAM Module
    participant G as Google Auth
    participant A as Auth App

    U->>S: ssh user@server
    S->>D: Connection request
    D->>S: Public key challenge
    S->>D: Public key response
    D->>P: Verify authentication
    P->>G: Request TOTP
    G->>S: Prompt for code
    U->>A: Check code
    A->>U: Display code
    U->>S: Enter code
    S->>D: Submit code
    D->>G: Verify TOTP
    G->>P: Valid
    P->>D: Authentication success
    D->>S: Access granted

Test Commands#

1
# Test with verbose output
2
ssh -v user@server
3

4
# Test specific authentication method
5
ssh -o PreferredAuthentications=publickey,keyboard-interactive user@server
6

7
# Test from different terminal
8
# Keep current session open!
9
ssh user@localhost

Advanced Configuration#

Backup Codes#

1
# Generate additional backup codes
2
google-authenticator --emergency-codes=10
3

4
# Store securely
5
cat ~/.google_authenticator | grep -E "^[0-9]{8}$" > ~/backup-codes.txt
6
chmod 600 ~/backup-codes.txt

Multiple Devices#

1
#!/bin/bash
2
# Extract secret key
3
SECRET=$(head -1 ~/.google_authenticator)
4

5
# Generate QR code URL
6
USER=$(whoami)
7
HOSTNAME=$(hostname)
8
URL="otpauth://totp/${USER}@${HOSTNAME}?secret=${SECRET}&issuer=SSH"
9

10
# Display QR code
11
qrencode -t UTF8 "$URL"
12

13
# Or save as image
14
qrencode -o ~/qr-code.png "$URL"

Conditional 2FA#

1
# Skip 2FA for certain conditions
2
# Create /etc/security/access-local.conf
3
+ : ALL : 192.168.1.0/24
4
+ : ALL : LOCAL
5
- : ALL : ALL
6

7
# Update PAM configuration
8
auth [success=1 default=ignore] pam_access.so accessfile=/etc/security/access-local.conf
9
auth required pam_google_authenticator.so

Security Hardening#

SELinux Configuration#

1
# Check SELinux status
2
getenforce
3

4
# Allow Google Authenticator in SELinux
5
sudo setsebool -P authlogin_yubikey on
6

7
# Create custom policy if needed
8
sudo ausearch -c 'sshd' --raw | audit2allow -M my-sshd-2fa
9
sudo semodule -i my-sshd-2fa.pp

File Permissions#

1
# Secure Google Authenticator files
2
chmod 600 ~/.google_authenticator
3
chmod 700 ~
4

5
# System-wide permissions
6
sudo chmod 644 /etc/pam.d/sshd
7
sudo chmod 644 /etc/ssh/sshd_config

Audit Logging#

1
# Enable detailed PAM logging
2
# Add to /etc/pam.d/sshd
3
auth required pam_google_authenticator.so debug
4

5
# Monitor authentication attempts
6
sudo tail -f /var/log/auth.log  # Debian/Ubuntu
7
sudo tail -f /var/log/secure    # RHEL/CentOS
8

9
# Configure rsyslog for 2FA events
10
echo "auth.*  /var/log/2fa.log" | sudo tee -a /etc/rsyslog.conf
11
sudo systemctl restart rsyslog

Automation Scripts#

Bulk User Setup#

1
#!/bin/bash
2
USERS_FILE="users.txt"
3
QR_OUTPUT_DIR="/tmp/qr-codes"
4

5
mkdir -p "$QR_OUTPUT_DIR"
6

7
while IFS= read -r username; do
8
    echo "Setting up 2FA for $username..."
9

10
    # Generate secret
11
    su - "$username" -c "google-authenticator \
12
        --time-based \
13
        --disallow-reuse \
14
        --force \
15
        --rate-limit=3 \
16
        --rate-time=30 \
17
        --window-size=3"
18

19
    # Extract secret and generate QR
20
    SECRET=$(su - "$username" -c "head -1 ~/.google_authenticator")
21
    URL="otpauth://totp/${username}@$(hostname)?secret=${SECRET}"
22

23
    # Save QR code
24
    qrencode -o "$QR_OUTPUT_DIR/${username}-qr.png" "$URL"
25

26
    echo "QR code saved to: $QR_OUTPUT_DIR/${username}-qr.png"
27
done < "$USERS_FILE"

Monitoring Script#

1
#!/bin/bash
2
LOG_FILE="/var/log/auth.log"
3
ALERT_EMAIL="admin@example.com"
4

5
# Monitor for 2FA failures
6
tail -F "$LOG_FILE" | while read line; do
7
    if echo "$line" | grep -q "Failed to authenticate"; then
8
        echo "2FA failure detected: $line" | \
9
            mail -s "2FA Authentication Failure" "$ALERT_EMAIL"
10
    fi
11
done

Recovery Procedures#

Lost Device Recovery#

graph TD
    A[Lost Device] --> B{Backup Codes?}
    B -->|Yes| C[Use Backup Code]
    B -->|No| D{Root Access?}

    C --> E[Login Success]

    D -->|Yes| F[Disable 2FA Temporarily]
    D -->|No| G[Contact Admin]

    F --> H[Regenerate Secret]
    G --> I[Admin Assistance]

    H --> J[Re-enable 2FA]
    I --> J

    style A fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px
    style E fill:#51cf66,stroke:#2f9e44,stroke-width:2px
    style J fill:#74c0fc,stroke:#1971c2,stroke-width:2px

Emergency Access#

1
# As root, temporarily disable 2FA for a user
2
# Option 1: Remove .google_authenticator file
3
sudo mv /home/user/.google_authenticator /home/user/.google_authenticator.disabled
4

5
# Option 2: Comment out PAM line
6
sudo sed -i 's/^auth required pam_google_authenticator.so/#&/' /etc/pam.d/sshd
7
sudo systemctl restart sshd
8

9
# Option 3: Add bypass for specific user
10
echo "auth sufficient pam_succeed_if.so user = emergencyuser" | \
11
    sudo tee -a /etc/pam.d/sshd

Regenerate Secret#

1
#!/bin/bash
2
USER=$1
3

4
if [ -z "$USER" ]; then
5
    echo "Usage: $0 <username>"
6
    exit 1
7
fi
8

9
# Backup old secret
10
sudo mv /home/$USER/.google_authenticator \
11
       /home/$USER/.google_authenticator.old
12

13
# Generate new secret
14
sudo -u $USER google-authenticator \
15
    --time-based \
16
    --disallow-reuse \
17
    --force \
18
    --rate-limit=3 \
19
    --rate-time=30 \
20
    --window-size=3
21

22
echo "New 2FA secret generated for $USER"

Troubleshooting#

Common Issues#

Time Sync Problems

1
# Check time difference
2
ntpdate -q time.google.com
3

4
# Force sync
5
sudo ntpdate -s time.google.com
6

7
# Increase time window
8
auth required pam_google_authenticator.so window_size=10

SELinux Denials

1
# Check SELinux logs
2
sudo ausearch -m avc -ts recent
3

4
# Generate policy
5
sudo audit2allow -a -M google_auth
6
sudo semodule -i google_auth.pp

PAM Module Not Found

1
# Find PAM module
2
find /lib* -name "pam_google_authenticator.so"
3

4
# Create symlink if needed
5
sudo ln -s /usr/lib64/security/pam_google_authenticator.so \
6
           /lib64/security/pam_google_authenticator.so

Debug Mode#

1
# Enable SSH debug
2
sudo /usr/sbin/sshd -d -p 2222
3

4
# Enable PAM debug
5
auth required pam_google_authenticator.so debug
6

7
# Check system logs
8
journalctl -xe | grep -i "pam\|ssh\|google"

Best Practices#

Security Recommendations#

graph TD
    A[2FA Best Practices] --> B[Regular Updates]
    A --> C[Secure Storage]
    A --> D[Monitoring]
    A --> E[Backup Plans]

    B --> F[Update PAM modules]
    B --> G[Patch SSH server]

    C --> H[Encrypt backup codes]
    C --> I[Secure secret files]

    D --> J[Log analysis]
    D --> K[Failed attempts alerts]

    E --> L[Multiple admins with 2FA]
    E --> M[Recovery procedures]

    style A fill:#4ecdc4,stroke:#087f5b,stroke-width:2px
    style C fill:#ff6b6b,stroke:#c92a2a,stroke-width:2px
    style D fill:#74c0fc,stroke:#1971c2,stroke-width:2px

Implementation Checklist#

Integration Examples#

Ansible Playbook#

1
---
2
- name: Configure Google Authenticator 2FA
3
  hosts: all
4
  become: yes
5
  tasks:
6
    - name: Install Google Authenticator
7
      package:
8
        name: google-authenticator
9
        state: present
10

11
    - name: Configure PAM
12
      lineinfile:
13
        path: /etc/pam.d/sshd
14
        line: "auth required pam_google_authenticator.so nullok"
15
        insertafter: "@include common-auth"
16

17
    - name: Configure SSH
18
      lineinfile:
19
        path: /etc/ssh/sshd_config
20
        regexp: "^ChallengeResponseAuthentication"
21
        line: "ChallengeResponseAuthentication yes"
22
      notify: restart sshd
23

24
  handlers:
25
    - name: restart sshd
26
      service:
27
        name: sshd
28
        state: restarted

Docker Container Support#

1
FROM ubuntu:22.04
2

3
RUN apt-get update && \
4
    apt-get install -y openssh-server google-authenticator
5

6
# Configure SSH for container
7
RUN mkdir /var/run/sshd && \
8
    echo 'ChallengeResponseAuthentication yes' >> /etc/ssh/sshd_config && \
9
    echo 'UsePAM yes' >> /etc/ssh/sshd_config
10

11
# Add PAM configuration
12
RUN echo "auth required pam_google_authenticator.so nullok" >> /etc/pam.d/sshd
13

14
EXPOSE 22
15
CMD ["/usr/sbin/sshd", "-D"]

Conclusion#

Implementing Google Authenticator for SSH provides robust two-factor authentication that significantly enhances server security. Key benefits include:

Strong Security: Time-based tokens resistant to replay attacks
Easy Integration: Works with existing SSH infrastructure
Flexible Configuration: Supports various authentication combinations
Wide Compatibility: Works with multiple authenticator apps
Cost-Effective: Free and open-source solution

Best practices for deployment:

Always test in a non-production environment first
Keep backup codes in a secure location
Document recovery procedures
Monitor authentication logs
Regularly update security components
Train users on proper 2FA usage

With proper implementation, Google Authenticator provides enterprise-grade security for SSH access while maintaining usability.