Troubleshooting Google Authenticator MFA Codes Not Working in Linux

Google Authenticator MFA codes fail in Linux primarily due to time synchronization drift, incorrect PAM configuration order, or permission issues with the .google_authenticator file. Verify system time accuracy using timedatectl, ensure pam_google_authenticator.so is placed correctly in /etc/pam.d/sshd, and confirm the user has read access to their secret key file.

Verifying System Time Synchronization

The most common cause for TOTP (Time-based One-Time Password) failures is a discrepancy between the server’s clock and the authenticator app on your mobile device. Google Authenticator relies on strict time alignment; if the server time is off by more than 30 seconds, the generated code will be rejected. In modern Debian and Ubuntu systems, ntpq is obsolete because these distributions use systemd-timesyncd for time management. First, check the current status of your time synchronization service. Run the following command to see if the daemon is active and synchronized:

timedatectl status

Look for the line that says "NTP service: active". If it says "inactive", your system time may not be syncing with external NTP servers. You can manually enable and start the service using:

sudo timedatectl set-ntp true

After enabling NTP, wait a minute for the sync to occur, then verify the time again. Compare the displayed local time with a reliable source like an atomic clock website. If the difference is significant, you may need to manually adjust the time or check your network connectivity to the NTP pool servers. Persistent drift might indicate a hardware clock issue or firewall rules blocking UDP port 123.

Configuring PAM Correctly

Linux uses Pluggable Authentication Modules (PAM) to handle authentication processes. The order in which modules are loaded in /etc/pam.d/sshd is critical. If the password prompt appears before the Google Authenticator challenge, users might enter their password first, causing the session to fail when the second factor is later requested. Open the SSH PAM configuration file:

sudo nano /etc/pam.d/sshd

Ensure that the line loading the Google Authenticator module appears before the standard password authentication line. It should look something like this:

auth required pam_google_authenticator.so
@include common-auth

The @include common-auth directive handles the regular password check. By placing the MFA requirement first, the system prompts for the one-time code immediately upon login attempt. After making changes, test the configuration syntax without restarting the entire service to avoid locking yourself out:

sshd -t

If this command returns no errors, restart the SSH service:

sudo systemctl restart sshd

Misconfiguration here often leads to confusion where users think the MFA is broken, but it is actually a sequencing issue. For more details on how permission changes can inadvertently break sudo or SSH access, see How did this usage of chmod break sudo access?.

Checking File Permissions and Ownership

The .google_authenticator file in the user's home directory contains sensitive secrets and must have restrictive permissions. If the file is world-readable or writable, Google Authenticator may refuse to use it for security reasons. Additionally, if the file is owned by root instead of the user, the application cannot read the keys. Check the permissions and ownership of the file:

ls -l ~/.google_authenticator

The output should show permissions like -rw------- (600) and be owned by the specific user (e.g., john). If the permissions are too open, correct them immediately:

chmod 600 ~/.google_authenticator

If the ownership is incorrect, fix it using:

sudo chown $USER:$USER ~/.google_authenticator

In some cases, users attempt to reset their MFA setup by deleting the file and running google-authenticator again. Ensure you do this as the target user, not as root, to maintain proper ownership. Incorrect ownership can also affect other authentication methods, leading to broader access issues similar to those described in Sudo asks for password, even the ssh key method is setup for newly created user.

Debugging with Logs

If the above steps do not resolve the issue, inspect the system logs for detailed error messages. SSH authentication attempts are logged in /var/log/auth.log (Debian/Ubuntu) or /var/log/secure (RHEL/CentOS). Monitor the log in real-time while attempting to log in:

sudo tail -f /var/log/auth.log

Look for entries related to pam_google_authenticator. Common errors include "authentication failure" or "invalid token." If you see messages indicating that the time window has expired, revisit the time synchronization section. If you see permission denied errors, recheck the file ownership. Sometimes, the issue lies with the client-side application rather than the server. Ensure your mobile app is not set to a different timezone that doesn't align with the server's UTC time. Most apps allow you to manually adjust the time offset during setup if automatic synchronization fails.

Recovering from Lockouts

If you accidentally lock yourself out by misconfiguring PAM or changing permissions incorrectly, you may need emergency access. Do not attempt to edit files remotely if you are already locked out. Instead, use the console access provided by your VPS provider or physical console if available. Once logged in via console, you can temporarily comment out the Google Authenticator line in /etc/pam.d/sshd by adding a # at the beginning of the line. This allows you to regain SSH access and correct the configuration. Always keep a backup of the original file before making changes:

sudo cp /etc/pam.d/sshd /etc/pam.d/sshd.bak

For guidance on recovering access when standard authentication methods fail, refer to How to Retrieve the Default User Password in Linux Distribution's ISO Image.

Frequently Asked Questions

Why does my code work once but then fail?

This usually indicates a time drift issue where the server clock has shifted slightly since the initial sync. Restart the systemd-timesyncd service to force a resync with NTP servers and verify the time matches your device.

Can I use Google Authenticator with SSH keys only?

No, Google Authenticator adds a second factor to existing authentication methods. If you use SSH keys, the MFA will prompt after the key is accepted, requiring both the key and the code for full access.

What happens if I lose my phone?

You can recover access by using the backup codes provided when you first set up Google Authenticator. If you didn’t save them, you must delete the .google_authenticator file via console access and regenerate a new QR code.

Does Debian 11 require a different PAM setup?

The PAM configuration remains consistent across recent Debian versions. However, ensure you are editing the correct file for your service, such as /etc/pam.d/sshd for SSH or /etc/pam.d/login for local console access.

How do I know if PAM is loading my module?

Check the auth log for lines containing pam_google_authenticator. If you see errors about missing libraries, ensure the package libpam-google-authenticator is installed and properly linked.