PAM Authentication Basics

PAM Authentication Basics

PAM (Pluggable Authentication Modules) is the authentication framework that all Ubuntu services use. When you log in via SSH, use sudo, or run su, PAM handles the authentication, account validation, session setup, and password management. Understanding PAM is essential because misconfiguring it can lock you out of the system permanently.

What PAM does

Application (sshd, sudo, login)
         |
         v
    PAM Framework
         |
    reads /etc/pam.d/sshd
         |
    ┌────┴──────────────────────────────────┐
    │  auth   → Who are you? (password/key) │
    │  account → Is your account valid?      │
    │  session → Set up environment          │
    │  password → How to change password     │
    └───────────────────────────────────────┘
         |
    Each step calls one or more modules (pam_unix.so, pam_google_authenticator.so, etc.)
         |
    Result: allow or deny access

PAM configuration files

# Each service has its own PAM config in /etc/pam.d/
ls /etc/pam.d/

# Key files:
# /etc/pam.d/common-auth     — included by most services for auth
# /etc/pam.d/common-account  — account validation
# /etc/pam.d/common-session  — session management
# /etc/pam.d/common-password — password changing
# /etc/pam.d/sshd            — SSH-specific overrides
# /etc/pam.d/sudo            — sudo-specific
# /etc/pam.d/login           — console login

# View a service's PAM config
cat /etc/pam.d/sshd

Example /etc/pam.d/sshd structure

# Standard auth for sshd
@include common-auth

# Account checking (expiry, lockout, access restrictions)
@include common-account

# Session setup (home directory, limits, environment)
@include common-session

# Password changing (rare for SSH, but included)
@include common-password

PAM module types

PAM control flags

# Example auth stack from /etc/pam.d/common-auth:
auth    [success=1 default=ignore]  pam_unix.so nullok
auth    requisite                   pam_deny.so
auth    required                    pam_permit.so

# Reading this:
# 1. Try pam_unix (password check). If success: skip 1 module (jump to pam_permit).
# 2. If pam_unix fails: run pam_deny (which always fails) → requisite means STOP immediately.
# 3. pam_permit always succeeds (only reached via the skip in step 1).

Common PAM modules

Testing PAM changes safely

# CRITICAL: Before editing any PAM file, open a second root session
# If you break PAM, you need that session to undo the change
sudo -i  # Open a root shell in a separate terminal tab first

# Test the PAM configuration without applying it
pamtester sshd testuser authenticate

# If testing authentication from command line:
ssh -v testuser@localhost 2>&1 | grep -E "auth|PAM"

# Check PAM errors in logs
sudo journalctl -u ssh --since "1 minute ago" | grep -i pam
sudo grep "pam" /var/log/auth.log | tail -20

⚠️ WARNING: PAM configuration errors can lock ALL users out of the system, including root. Before editing any PAM file, open a separate root session (sudo -i in a new terminal). Test changes with pamtester before closing the original session. If authentication breaks, use the open root session to revert the change.

Conclusion

PAM is the authentication backbone of Ubuntu. All service authentication flows through it. The most important safety rule: always have a separate root session open when editing PAM configuration files, because a syntax error or wrong module can lock you out instantly. Understand the four module types (auth, account, session, password) and the control flags (required, requisite, sufficient, optional) before making changes. Test with pamtester and verify in logs before considering a change complete.