How to Set Up Google Authenticator for SSH 2FA on FreeBSD

Securing remote access to a FreeBSD server is crucial, and enabling two-factor authentication (2FA) for SSH is an excellent way to add an extra layer of security. Google Authenticator is a popular choice for implementing Time-based One-Time Passwords (TOTP) for 2FA. This guide will walk you through setting up Google Authenticator for SSH login on FreeBSD.

Prerequisites

Before you begin, ensure you have the following:

• A FreeBSD system with root or sudo access.
• SSH configured and running.
• A mobile device with the Google Authenticator app installed.
• Basic familiarity with the FreeBSD command line.

Step 1: Install Google Authenticator PAM Module

Google Authenticator requires the pam_google_authenticator module to generate and validate OTPs. Install it using the FreeBSD package manager:

sudo pkg install pam_google_authenticator

If using ports, you can install it with:

cd /usr/ports/security/pam_google_authenticator
make install clean

Step 2: Configure Google Authenticator for Your User

Each user who will use 2FA needs to configure Google Authenticator individually. Log in as the user and run:

google-authenticator

You will be prompted with several questions. Answer as follows:

• Do you want authentication tokens to be time-based? Enter y.
• A QR code will be displayed. Scan it using the Google Authenticator app on your phone.
• Save the provided emergency backup codes in a secure location.
• Do you want me to update your .google_authenticator file? Enter y.
• Do you want to disallow multiple uses of the same token? Enter y.
• Do you want to increase the time window? Enter n unless you experience frequent login failures due to time sync issues.
• Do you want to enable rate-limiting? Enter y to limit login attempts.

This process generates a .google_authenticator file in the user’s home directory.

Step 3: Configure SSH to Use Google Authenticator

Modify the SSH PAM configuration file to enable Google Authenticator. Open the file:

sudo vi /etc/pam.d/sshd

Add the following line at the top:

auth required /usr/local/lib/pam_google_authenticator.so

Save and exit.

Next, modify the SSH daemon configuration file:

sudo vi /etc/ssh/sshd_config

Locate and modify (or add) the following lines:

ChallengeResponseAuthentication yes
UsePAM yes

Optionally, ensure that PasswordAuthentication is enabled to allow password+OTP authentication:

PasswordAuthentication yes

Save the file and restart the SSH service:

sudo service sshd restart

Step 4: Test the Setup

Open a new terminal and try logging into your FreeBSD server:

ssh your_user@your_server_ip

You should be prompted for your password first and then the verification code from the Google Authenticator app.

Step 5: Enforce 2FA for All Users (Optional)

To require 2FA for all SSH logins, edit the PAM configuration again and ensure the following line is included:

auth required /usr/local/lib/pam_google_authenticator.so nullok

The nullok option allows users without a .google_authenticator file to log in without 2FA. If you want to enforce 2FA for everyone, remove nullok.

Step 6: Troubleshooting

If you encounter issues, consider the following:

• Authentication fails: Ensure time synchronization between your server and phone using ntpdate or ntpd.
• No prompt for OTP: Verify that ChallengeResponseAuthentication is set to yes in sshd_config.
• Users locked out: Temporarily disable Google Authenticator by removing its entry from /etc/pam.d/sshd and restarting SSH.

Conclusion

Enabling Google Authenticator for SSH on FreeBSD significantly enhances security by requiring an additional verification step. Following this guide ensures that your remote logins are better protected against unauthorized access. Regularly updating your authentication methods and maintaining secure backup codes will help maintain secure access.