Linux › Section G · System configuration › Topic G.8

Pluggable Authentication Modules

Programs such as login, sshd, sudo and passwd do not each contain their own password-checking code. They ask PAM, a library that reads a small configuration file and runs a chain of modules, so an administrator can change a login policy without touching the programs.

Why PAM exists

Before PAM, every program that needed to check a user (login, ftp daemons, su) carried its own authentication code. Adding a new method, such as a smartcard or a directory server, meant rebuilding each of them. Pluggable Authentication Modules separate the two roles. The application calls the PAM library and asks the questions: can this person authenticate, may they use this service now, may they change a password, and can a session be opened? The library answers by running modules named in a configuration file. Change the file, and every program that uses the service follows the new policy.

Where the rules live and how a line reads

Each service has a file in /etc/pam.d/ named after it in lower case: login, sshd, sudo, su, passwd, and so on. (A single legacy file, /etc/pam.conf, uses the same lines with an extra leading service field.) A line has the form type control module-path arguments. The module is usually a bare name such as pam_unix.so, which PAM finds in its security directory; an absolute path also works. Arguments follow, separated by spaces. Lines run top to bottom within each type. A type written with a leading minus, such as -auth, tells PAM not to log an error if the module is missing.

Four management groups

The type says which question a line answers. auth verifies identity, for example by checking a password, and may grant credentials. account makes access decisions that are not about identity: has the password or account expired, is the time of day allowed, is the login source permitted. password handles changing the authentication token, including checks on password strength. session sets up and tears down around a login, for example logging, mounting a directory or setting limits. One program may use all four: logging in checks auth and account, then opens a session, and passwd uses password.

Control flags decide what a result means

The control field says how a module's result affects the whole stack. required: failure is reported, but only after the rest of the stack has run. requisite: failure returns immediately. sufficient: success ends the stack at once, provided no earlier required module failed; failure is ignored. optional: matters only if it is the only module of that type. include pulls in all lines of that type from another file, and substack does the same but treats the result as a single module. Advanced users write a bracket form such as [success=ok default=bad]; the plain keywords are shorthand for set bracket patterns.

Common modules

pam_unix.so checks passwords against /etc/shadow and, in the account group, tests ageing and expiry fields; in the password group its arguments such as sha512 or yescrypt choose the hash. pam_deny.so always fails and pam_permit.so always succeeds. pam_faillock.so counts failed attempts and locks an account for a time; its limits come from /etc/security/faillock.conf, for example deny=4 and unlock_time=1200 (seconds, 20 minutes). pam_pwquality.so rejects weak passwords according to /etc/security/pwquality.conf. pam_limits.so applies per-user resource limits from /etc/security/limits.conf. pam_nologin.so honours /etc/nologin, and pam_wheel.so restricts a service such as su to a group.

Worked example: tracing a stack

Read this auth stack for a service: line 1, auth required pam_env.so; line 2, auth sufficient pam_unix.so; line 3, auth required pam_deny.so. Case one: the right password. 1. pam_env succeeds (it just sets variables). 2. pam_unix succeeds; because it is sufficient and no earlier required module failed, the stack ends with success and pam_deny never runs. Case two: a wrong password. 3. pam_env still succeeds. 4. pam_unix fails, but a sufficient failure is ignored. 5. pam_deny runs and always fails; it is required, so the overall result is failure. Check: pam_deny acts as a safety net, so reaching the end of the stack means no earlier module vouched for the user.

Worked example: required versus requisite

A su service has these auth lines in order: pam_env.so (required), pam_wheel.so use_uid (required), pam_unix.so (sufficient). A user who is not in the wheel group types the correct password. 1. pam_env succeeds. 2. pam_wheel fails, and because it is required the failure is recorded but processing continues. 3. pam_unix succeeds, but sufficient only ends the stack with success when no earlier required module failed. 4. The earlier failure stands, so the overall result is failure. The user was still asked for a password first, since required hides which module failed. 5. If pam_wheel were requisite, the stack would end at line 2, and no password prompt would appear at all.

Per-distribution layout

Real files are shorter than they look, because they include shared stacks. Debian-family services pull in common-auth, common-account, common-password and common-session with @include lines, and pam-auth-update builds those shared files from small profiles. Fedora and RHEL families use system-auth and password-auth, generated by the authselect tool, and a direct edit of these generated files can be overwritten, so use authselect to change them. Either way, a service file such as /etc/pam.d/sshd mostly lists a few service-specific modules, such as pam_nologin, and then includes the shared policy.

Changing policy safely

A mistake in a PAM file can lock out every user, including root and sudo. Before editing, open a second terminal with a root shell and leave it open; copy the file to a backup; make one change at a time; and test with a new login from a third terminal before closing anything. On modern systems, prefer the supported tools (pam-auth-update or authselect) and the module's own configuration files, such as faillock.conf, over rewriting stacks by hand. Review the changes after upgrades, because package updates may add or rewrite PAM files, and remember that the account group, not auth, is where expiry and time-of-day rules live.

Common mistakes to avoid

First, using sufficient where required is needed, so a single success skips later checks. Second, ordering lines wrongly: PAM runs them top to bottom within a type. Third, expecting auth to enforce account expiry; that belongs to account. Fourth, leaving no safety net, such as a spare root session. Fifth, confusing include and substack. Sixth, editing authselect- or pam-auth-update-generated files directly. Seventh, assuming a PAM change affects sessions already open; it applies to the next authentication.

Key takeaways

PAM lets programs delegate authentication to modules configured in /etc/pam.d/SERVICE. A line is type, control, module, arguments. The types are auth, account, password and session. required fails late, requisite fails at once, sufficient succeeds early only if no earlier required module failed, and optional rarely matters. pam_unix handles passwords, pam_deny always fails, pam_faillock locks accounts, pam_pwquality checks strength, and pam_limits sets limits. Edit with a spare root shell open, and prefer pam-auth-update or authselect.

Flashcards

Flashcard

PAM

Library that lets programs delegate authentication to modules

Policy is set by configuration files.

Test your understanding

Question 1 of 5

In a PAM stack, which control flag makes a failing module end the stack immediately?

Question 2 of 5

The auth stack is pam_env required, pam_unix sufficient, pam_deny required. A user types a wrong password. What is the result?

Question 3 of 5

In a su stack, pam_wheel.so is required and fails, then pam_unix.so is sufficient and succeeds. What is the overall result?

Question 4 of 5

Which PAM management group would hold a rule that blocks logins outside working hours or for an expired account?

Question 5 of 5

Where does the PAM configuration for the SSH server normally live?

← Previous topicNext topic →