Setting Up PAM Google Authentication for 2FA on macOS

This document provides step-by-step instructions to set up Google PAM authentication on macOS to enable Two-Factor Authentication (2FA) for system logins.

Prerequisites

1. Administrator Privileges: You must have admin rights on the macOS system.
2. Homebrew: Ensure Homebrew is installed. If not, install it using:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Google Authenticator: Install the Google Authenticator app on your mobile device (available on iOS and Android).

Step 1: Install Google PAM Module

1. Open a terminal.
2. Install the PAM Google Authenticator module using Homebrew:

brew install google-authenticator-libpam

Step 2: Configure PAM Google Authenticator

1. Switch to the user account for which you want to enable 2FA:

su - <username>

2. Generate the Google Authenticator configuration file by running:

google-authenticator

3. Follow the on-screen prompts:

• Time-based tokens: Type y to use time-based tokens.
• Secret key and QR code: Note the key or scan the QR code with your Google Authenticator app.
• Emergency scratch codes: Save these for account recovery.
• Rate limiting: Type y to enable rate limiting.
• Disallow multiple uses: Type y to disallow multiple uses of the same token.

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

Step 3: Configure PAM

1. Open the PAM configuration file for SSH logins:

sudo nano /etc/pam.d/sshd

2. Add the following line at the top of the file:

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

3. Save and exit the file.

Step 4: Enable Challenge-Response Authentication

1. Open the SSH configuration file:

sudo nano /etc/ssh/sshd_config

1. Find and modify the following lines:

ChallengeResponseAuthentication yes 
UsePAM yes

2. Save and exit the file.

3. Restart the SSH service:

sudo launchctl stop com.openssh.sshd 

sudo launchctl start com.openssh.sshd

Step 5: Test the Configuration

1. Open a new terminal or SSH session and log in as the configured user.
2. You should be prompted for:

• Your password.
• A verification code from your Google Authenticator app.

3. If both are correct, you will successfully log in.

Step 6: Enable Local Console Login with 2FA

1. Open the PAM configuration file for local logins:

sudo nano /etc/pam.d/login

2. Add the following line at the top of the file:

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

3. Save and exit the file.

4. Log out and test logging in locally with 2FA.

Troubleshooting

• Missing PAM Module: If you see an error related to the PAM module, verify the installation path:

ls /usr/local/lib/security/

• Ensure pam_google_authenticator.so exists.
• Backup Codes Not Working: Check the .google_authenticator file in the user's home directory and ensure it has valid recovery codes.
• SSH Login Issues: Confirm UsePAM and ChallengeResponseAuthentication are set to yes in /etc/ssh/sshd_config.

Notes

• Ensure the system time is synced correctly to avoid authentication failures.
• Periodically review .google_authenticator file permissions:

chmod 400 ~/.google_authenticator

• Use 2FA for all admin accounts to enhance security.

This setup ensures added security to your macOS system by requiring both a password and a 2FA code for user logins.