How to Implement Two-Factor Authentication with PAM on Debian 12 Bookworm

In an age where digital threats are becoming increasingly sophisticated, relying on just a username and password to protect your Linux system is no longer sufficient. Two-Factor Authentication (2FA), particularly time-based one-time passwords (TOTP), adds an essential extra layer of security. On Debian 12 “Bookworm”, you can implement 2FA using the Pluggable Authentication Module (PAM) framework, specifically with Google Authenticator or other TOTP-compatible applications.

In this article, we’ll walk you through a complete guide on setting up and enforcing two-factor authentication on your Debian 12 system using PAM. Whether you’re securing SSH logins or local terminal access, these steps will help you add strong authentication measures to your environment.

Table of Contents

1. What is Two-Factor Authentication (2FA)?
2. Understanding PAM (Pluggable Authentication Module)
3. Requirements and Assumptions
4. Step-by-Step Guide
   • Installing Google Authenticator PAM Module
   • Setting Up TOTP for Individual Users
   • Configuring PAM to Use Google Authenticator
   • Enforcing 2FA for SSH Access
5. Testing Your 2FA Setup
6. Optional: Backup Codes and Recovery
7. Security Considerations and Best Practices
8. Conclusion

1. What is Two-Factor Authentication (2FA)?

Two-Factor Authentication enhances security by requiring two types of credentials:

1. Something you know (e.g., a password)
2. Something you have (e.g., a time-based token from a smartphone app)

TOTP is a popular 2FA method where a new token is generated every 30 seconds. This token is typically stored and accessed via applications like Google Authenticator, FreeOTP, or Authy on a mobile device.

2. Understanding PAM (Pluggable Authentication Module)

PAM is a modular authentication system used by Linux and UNIX systems. It provides a flexible mechanism for authenticating users by dynamically loading authentication modules. This makes it perfect for integrating 2FA into system login and SSH authentication.

By modifying the PAM configuration, you can instruct the system to require both a password and a TOTP code before granting access.

3. Requirements and Assumptions

• A running Debian 12 (Bookworm) system
• Root or sudo access
• An SSH server installed (optional, if remote access is required)
• A TOTP-compatible app on your mobile device (e.g., Google Authenticator)

4. Step-by-Step Guide

Step 1: Installing Google Authenticator PAM Module

The first step is to install the required PAM module.

sudo apt update
sudo apt install libpam-google-authenticator

This package includes the google-authenticator tool, which each user can use to set up their own TOTP key.

Step 2: Setting Up TOTP for Individual Users

Each user must initialize their own TOTP configuration. Start with the current user (or a test user):

google-authenticator

You’ll be prompted with several questions:

• Do you want authentication tokens to be time-based (y/n)? → Type y
• A QR code and secret key will be displayed. Scan this using your TOTP app.
• The system will also show emergency scratch codes. Save them in a secure location.
• Answer y to rate-limiting, token reuse prevention, and configuration saving.

This command will generate a .google_authenticator file in the user’s home directory (~/.google_authenticator). Make sure the file is readable only by the user:

chmod 600 ~/.google_authenticator

Step 3: Configuring PAM to Use Google Authenticator

To enable PAM to work with the 2FA module, edit the PAM configuration file for login.

For local logins (console):

sudo nano /etc/pam.d/login

Add the following line at the top or just after auth [success=1 default=ignore] pam_unix.so:

auth required pam_google_authenticator.so

For SSH logins:

sudo nano /etc/pam.d/sshd

Add:

auth required pam_google_authenticator.so

⚠️ Important: Do not remove existing pam_unix.so entries, as this module is still needed for password-based login.

Step 4: Enforcing 2FA for SSH Access

Edit the SSH server configuration to enable 2FA:

sudo nano /etc/ssh/sshd_config

Change or add the following lines:

ChallengeResponseAuthentication yes
UsePAM yes
PasswordAuthentication yes

Note: If you use public key authentication only and don’t want to require a password, you’ll need to modify the configuration further to support 2FA alongside key-based auth.

After saving the file, restart the SSH service:

sudo systemctl restart ssh

5. Testing Your 2FA Setup

Now test your SSH connection or local login:

ssh youruser@your-debian-ip

You’ll first be asked for your password, and then for the 6-digit verification code from your TOTP app.

If everything is configured correctly, you should be granted access only if both factors are successfully verified.

6. Optional: Backup Codes and Recovery

During the initial setup with google-authenticator, you were given backup codes. These are one-time use codes that can help you regain access if you lose your phone.

Recommendations:

• Store these codes offline in a secure location (e.g., encrypted USB drive or printed and locked).
• Consider enabling multiple devices for your TOTP key (e.g., a backup smartphone or tablet).

If a user loses access and has no backup, a system administrator can:

• Reset the ~/.google_authenticator file for that user
• Temporarily disable the PAM module for that user (not recommended unless absolutely necessary)

7. Security Considerations and Best Practices

• Enforce TOTP across all users: Audit and automate the presence of the .google_authenticator file for each user.
• Disable SSH password login (optional): For added security, you can require SSH keys plus TOTP, eliminating the password-based attack vector.
• Audit logs: Monitor /var/log/auth.log for 2FA failures and anomalies.
• Update packages regularly: Keep your system and PAM modules up to date.
• Disable root login via SSH: Edit /etc/ssh/sshd_config and set PermitRootLogin no.

8. Conclusion

Implementing two-factor authentication using PAM on Debian 12 Bookworm significantly strengthens your system’s security posture. It’s a relatively straightforward process that can prevent many types of unauthorized access, especially in remote environments. By combining something you know (password) with something you have (a TOTP code), you make it exponentially harder for attackers to compromise your system.

In environments where security is paramount—be it a personal server, a cloud-based production box, or a shared team system—adding this extra step is a simple, yet powerful upgrade.

Further Reading

• Debian Wiki on PAM
• Google Authenticator PAM GitHub
• OpenSSH Documentation