PAM authentication module failure — fix step by step

When this error hits

You're SSHing into a server or trying to log in at the console. You type your password, and instead of a shell you get:

Access denied
PAM: Authentication failure

Or maybe you see something like pam_unix(sshd:auth): authentication failure in /var/log/auth.log. I had a client last month whose entire team got locked out of their Ubuntu 20.04 server after a botched apt upgrade pulled a new PAM module version. No one could SSH in until I dropped in through the IPMI console.

Another common trigger: you edited /etc/pam.d/common-auth to add two-factor auth or tighten password rules, and now nothing works. Or you migrated from SSSD to LDAP and the PAM stack still references the old module path.

Root cause in plain English

PAM (Pluggable Authentication Modules) is a chain of checks. When you log in, each module in that chain runs in order. If one module fails, the whole chain fails. The root cause is almost always one of three things:

Missing module — a PAM config references a module that doesn't exist or got uninstalled.
Wrong module path — the config points to /lib/security/ but your system uses /lib/x86_64-linux-gnu/security/ (common after OS upgrades).
Typo or syntax error — a misspelled option or missing control flag like required vs requisite.

Less common but real: pam_tally2 or pam_faillock locked the account because someone brute-forced the password. That's not a config error, but it looks like one.

The fix — step by step

1. Check the auth log

First, find the exact error. On most Linux systems:

tail -50 /var/log/auth.log

On RHEL/CentOS/Fedora, it's usually /var/log/secure. Look for lines containing pam_unix, pam_sss, or the module you suspect. The log tells you which module failed and why. If it says module is unknown, you've found the issue.

2. Find the broken PAM config

If the error is during SSH, check /etc/pam.d/sshd. If it's local login, check /etc/pam.d/login or /etc/pam.d/system-auth (or common-auth on Debian/Ubuntu). Look for the line that references the failing module.

Example: you see pam_google_authenticator.so in the config, but it's not installed. Fix by installing the package or commenting the line out.

3. Verify the module exists on disk

Modules live in /lib/security/ or /lib/x86_64-linux-gnu/security/. Check with:

ls -la /lib/security/pam_unix.so
ls -la /lib/x86_64-linux-gnu/security/pam_unix.so

If the path in the config doesn't match the real path, you need to update the config. On a recent Ubuntu 22.04, the path changed from /lib/security/ to /lib/x86_64-linux-gnu/security/. A lot of old pam.d files still point to the old path.

4. Fix the syntax or typo

Open the config file. Look for lines like:

auth required pam_unix.so try_first_pass nullok

If you see auth requred (misspelled), that's your problem. Also check for extra spaces or missing control flags. The control field must be one of: required, requisite, sufficient, optional, or include. If you used required where you meant requisite, you'll get a different behavior but not necessarily a failure—still worth checking.

5. Fix account lockout

If the log says pam_tally2 or pam_faillock denied access, the account is locked. Reset it:

pam_tally2 --user=yourusername --reset
faillock --user yourusername --reset

Then try again.

6. Test the config with `pam-auth-update` (Debian/Ubuntu)

On Debian-based systems, run:

sudo pam-auth-update

This rewrites the common-* files from scratch based on installed modules. It's a good reset if you've messed things up.

7. Reinstall the PAM packages

As a last resort, reinstall the core PAM packages:

# Debian/Ubuntu
sudo apt install --reinstall libpam-modules libpam-runtime

# RHEL/CentOS
sudo yum reinstall pam

This restores missing module files.

If it still fails

Check these three things:

Is the SSH daemon using the right config? Some distros have /etc/pam.d/sshd but also include /etc/pam.d/system-auth. Comment out includes one by one to isolate.
Is the user in the right group? Some PAM modules check group membership. If pam_wheel.so is in the chain and the user isn't in wheel, su will fail.
Does auth.log show Permission denied before the PAM error? If so, the SSH key check failed, and PAM only runs as a fallback. Fix the SSH keys first.

If all else fails, boot into single-user mode or use a live CD to restore the original PAM config from backup. Always keep a backup of /etc/pam.d/ before making changes. I learned that the hard way.