============================================================
  PLUGGABLE AUTHENTICATION MODULES (PAM) REFERENCE GUIDE
============================================================
Author      : Tushar Sonawane
Date        : 09 September 2026
============================================================


1. OVERVIEW
-----------
Pluggable Authentication Modules (PAM) are a framework for system 
security. Modern Linux single sign-on (SSO) methods, such as Kerberos 
and Smart Cards, rely on PAM configuration.

PAM provides:
- A modular architecture for system administrators.
- A centralized authentication scheme for various applications.
- A library for developers to use instead of writing custom auth code.



2. CONFIGURATION LOCATION
-------------------------
Directory: /etc/pam.d/
Files: Each PAM-aware application has a file here named after the 
service (e.g., /etc/pam.d/login or /etc/pam.d/sshd).

3. CONFIGURATION FILE FORMAT
----------------------------
The syntax for directives is:
<interface>  <control_flag>  <module_name>  <module_arguments>

4. MODULE INTERFACES
--------------------
- auth: Verifies identity (passwords) and sets credentials.
- account: Checks if access is allowed (account expiry, time limits).
- password: Used for updating/changing user passwords.
- session: Manages the environment (mounting directories, logging).

Note: A single module file (e.g., pam_unix.so) can handle multiple 
interfaces.

5. CONTROL FLAGS
----------------
Control flags tell PAM how to handle the success or failure of a module:

REQUIRED: 
Result must be successful. If it fails, the user is not notified 
until all other modules in the stack are processed.

REQUISITE: 
Result must be successful. If it fails, the process terminates 
immediately and the user is notified.

SUFFICIENT: 
If it succeeds (and no previous REQUIRED modules failed), the user 
is authenticated immediately. If it fails, it is simply ignored.

OPTIONAL: 
Result is ignored unless no other modules are defined for that interface.

INCLUDE: 
Pulls in configuration lines from a different file.

6. MODULE NAMES AND ARGUMENTS
-----------------------------
MODULE NAMES:
The module name provides PAM with the name of the pluggable module 
containing the specified interface. The directory name is usually 
omitted because libpam is designed to locate the correct version 
of the module automatically.

MODULE ARGUMENTS:
Arguments pass specific information to a module. 
Example: auth required pam_userdb.so db=/path/to/database_file
Here, "db=" tells the module which database to use for authentication.

Note: Invalid arguments are generally ignored, but some modules may 
fail if an argument is incorrect. Errors are typically logged to 
/var/log/secure.

7. SAMPLE CONFIGURATION BREAKDOWN (/etc/pam.d/login)
----------------------------------------------------
#%PAM-1.0
auth      required  pam_securetty.so
auth      required  pam_unix.so      nullok
auth      required  pam_nologin.so
account   required  pam_unix.so
password  required  pam_cracklib.so  retry=3
password  required  pam_unix.so      shadow nullok use_authtok
session   required  pam_unix.so

Key Logic Explanations:
- pam_securetty: Prevents root login on insecure terminals.
- nullok: Allows blank passwords.
- pam_nologin: Respects the /etc/nologin file to block non-root users.
- pam_cracklib: Enforces strong password rules (strength checking).
- use_authtok: Forces pam_unix to use the password vetted by cracklib 
  rather than asking the user again.

8. LDAP SSHD CONFIGURATION BREAKDOWN (Word-by-Word)
---------------------------------------------------
Configuration:
auth        sufficient      pam_ldap.so
auth        include         system-auth
auth        include         postlogin

--- AUTHENTICATION ---
* auth sufficient pam_ldap.so
  - PAM checks the LDAP server. If the user provides a valid LDAP 
    password, authentication succeeds IMMEDIATELY (due to 'sufficient').
    If it fails, PAM moves to the next line.
* auth include system-auth / postlogin
  - If LDAP fails, PAM pulls in the standard local system 
    authentication rules and post-login logging.

--- ACCOUNT MANAGEMENT ---
* account sufficient pam_ldap.so
  - Checks if the LDAP account is valid (not expired). 
* account required pam_nologin.so
  - MANDATORY check to see if /etc/nologin exists (blocking users).
* account include system-auth
  - Pulls in standard local account policy checks.

--- PASSWORD MANAGEMENT ---
* password include system-auth
  - Redirects password changes to the standard system stack.

--- SESSION MANAGEMENT ---
* session required pam_mkhomedir.so skel=/etc/skel umask=0022
  - MANDATORY: Automatically creates a home directory for LDAP users 
    upon login if one does not exist, using /etc/skel as a template.
* session include system-auth / postlogin
  - Merges standard system session and post-login logging tasks.
* session required pam_loginuid.so
  - Sets the login UID for auditing and tracking.
* -session optional pam_elogind.so
  - The "-" prefix prevents errors if the module is missing. It 
    optionally manages user sessions/seats.

9. LOGGING AND TROUBLESHOOTING
------------------------------
Errors and authentication logs are typically sent to:
/var/log/secure

============================================================