PAM
PAM¶
How to Configure and Use PAM in Linux¶
Linux-PAM (short for Pluggable Authentication Modules which evolved from the Unix-PAM architecture) is a powerful suite of shared libraries used to dynamically authenticate a user to applications (or services) in a Linux system.
It integrates multiple low-level authentication modules into a high-level API that provides dynamic authentication support for applications. This allows developers to write applications that require authentication, independently of the underlying authentication system.
Many modern Linux distributions support Linux-PAM (hereinafter referred to as “PAM”) by default. We will explain how to configure advanced PAM for Proxmox and other Linux systems.
Before we proceed any further, note that:
- As a system administrator, the most important thing is to master how PAM configuration file(s) define the connection between applications (services) and the pluggable authentication modules (PAMs) that perform the actual authentication tasks. You don’t necessarily need to understand the internal working of PAM.
- PAM has the potential to seriously alter the security of your Linux system. Erroneous configuration can disable access to your system partially, or completely. For instance an accidental deletion of a configuration file(s) under /etc/pam.d/* and/or /etc/pam.conf can lock you out of your own system!
How to Check a Program is PAM-aware¶
To employ PAM, an application/program needs to be “PAM aware“; it needs to have been written and compiled specifically to use PAM. To find out if a program is “PAM-aware” or not, check if it has been compiled with the PAM library using the ldd command.
For example sshd:
sudo ldd /usr/sbin/sshd | grep libpam.so
libpam.so.0 => /lib/x86_64-linux-gnu/libpam.so.0 (0x0000751e9e465000)
How to Configure PAM in Linux¶
The main configuration file for PAM is /etc/pam.conf and the /etc/pam.d/ directory contains the PAM configuration files for each PAM-aware application/services. PAM will ignore the file if the directory exists.
The syntax for the main configuration file is as follows. The file is made up of a list of rules written on a single line (you can extend rules using the “\” escape character) and comments are preceded with “#” marks and extend to the next end of line.
The format of each rule is a space separated collection of tokens (the first three are case-insensitive). We will explain the these tokens in subsequent sections.
service type control-flag module module-arguments
where:
- service: actual application name.
- type: module type/context/interface.
- control-flag: indicates the behavior of the PAM-API should the module fail to succeed in its authentication task.
- module: the absolute filename or relative pathname of the PAM.
- module-arguments: space separated list of tokens for controlling module behavior.
The syntax of each file in /etc/pam.d/ is similar to that of the main file and is made up of lines of the following form:
type control-flag module module-arguments
This is a example of a rule definition (without module-arguments) found in the /etc/pam.d/sshd file, which disallows non-root logins when /etc/nologin exists:
account required pam_nologin.so
Understanding PAM Management Groups and Control-flags¶
PAM authentication tasks are separated into four independent management groups. These groups manage different aspects of a typical user’s request for a restricted service.
A module is associated to one these management group types:
- account: provide services for account verification: has the user’s password expired?; is this user permitted access to the requested service?.
- authentication: authenticate a user and set up user credentials.
- password: are responsible for updating user passwords and work together with authentication modules.
- session: manage actions performed at the beginning of a session and end of a session.
PAM loadable object files (the modules) are to be located in the following directory: /lib/security/ or /lib64/security depending on the architecture.
The supported control-flags are:
- requisite: failure instantly returns control to the application indicating the nature of the first module failure.
- required: all these modules are required to succeed for libpam to return success to the application.
- sufficient: given that all preceding modules have succeeded, the success of this module leads to an immediate and successful return to the application (failure of this module is ignored).
- optional: the success or failure of this module is generally not recorded.
In addition to the above are the keywords, there are two other valid control flags:
- include and substack: include all lines of given type from the configuration file specified as an argument to this control.
How to Restrict root Access to SSH Service Via PAM¶
As an example, we will configure how to use PAM to disable root user access to a system via SSH and login programs. Here, we want to disable root user access to a system, by restricting access to login and sshd services.
We can use the /lib/security/pam_listfile.so module which offers great flexibility in limiting the privileges of specific accounts. Open and edit the file for the target service in the /etc/pam.d/ directory as shown.
Add this rule in both files.
Explaining the tokens in the above rule:
- auth: is the module type (or context).
- required: is a control-flag that means if the module is used, it must pass or the overall result will be fail, regardless of the status of other modules.
- pam_listfile.so: is a module which provides a way to deny or allow services based on an arbitrary file.
- onerr=succeed: module argument.
- item=user: module argument which specifies what is listed in the file and should be checked for.
- sense=deny: module argument which specifies action to take if found in file, if the item is NOT found in the file, then the opposite action is requested.
- file=/etc/ssh/deniedusers: module argument which specifies file containing one item per line.
Next, we need to create the file /etc/ssh/deniedusers and add the name root in it:
Save the changes and close the file, then set the required permissions on it:
From now on, the above rule will tell PAM to consult the /etc/ssh/deniedusers file and deny access to the SSH and login services for any listed user.
How to Configuring Advanced PAM in Linux¶
To write more complex PAM rules, you can use valid control-flags in the following form:
type [value1=action1 value2=action2 …] module module-arguments
Where valueN corresponds to the return code from the function invoked in the module for which the line is defined. You can find supported values from the on-line PAM Administrator’s Guide. A special value is default, which implies all valueN’s not mentioned explicitly.
The actionN can take one of the following forms:
- ignore: if this action is used with a stack of modules, the module’s return status will not contribute to the return code the application obtains.
- bad: indicates that the return code should be thought of as indicative of the module failing. If this module is the first in the stack to fail, its status value will be used for that of the whole stack.
- die: equivalent to bad but may terminate the module stack and PAM immediately returning to the application.
- ok: this instructs PAM that the system administrator thinks this return code should contribute directly to the return code of the full stack of modules.
- done: equivalent to ok but may terminate the module stack and PAM immediately returning to the application.
- N (an unsigned integer): equivalent to ok but may jump over the next N modules in the stack.
- Reset: this action clears all memory of the state of the module stack and restart with the next stacked module.
Each of the four keywords: required; requisite; sufficient; and optional, have an equivalent expression in terms of the [...] syntax, which allow you to write more complicated rules and they are:
- required: [success=ok new_authtok_reqd=ok ignore=ignore default=bad]
- requisite: [success=ok new_authtok_reqd=ok ignore=ignore default=die]
- sufficient: [success=done new_authtok_reqd=done default=ignore]
- optional: [success=ok new_authtok_reqd=ok default=ignore]
The following is an example from a modern system. Let’s consider these rules from the /etc/pam.d/postlogin PAM file:
#%PAM-1.0
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
session [success=1 default=ignore] pam_succeed_if.so service !~ gdm* service !~ su* quiet
session [default=1] pam_lastlog.so nowtmp showfailed
session optional pam_lastlog.so silent noupdate showfailed
#%PAM-1.0
# This file is auto-generated.
# User changes will be destroyed the next time authconfig is run.
auth required pam_env.so
auth [success=done ignore=ignore default=die] pam_pkcs11.so nodebug wait_for_card
auth required pam_deny.so
account required pam_unix.so
account sufficient pam_localuser.so
account sufficient pam_succeed_if.so uid < 1000 quiet
account required pam_permit.so
password required pam_pkcs11.so
session optional pam_keyinit.so revoke
session required pam_limits.so
-session optional pam_systemd.so
session [success=1 default=ignore] pam_succeed_if.so service in crond quiet use_uid
session required pam_unix.so
For more information, see the pam.d man page:
Proxmox PAM Changes for SSH¶
Required Additions and or Changes¶
Software Installations
We need to install passwdqc - password/passphrase strength checking and enforcement.
- passwdqc is a password/passphrase strength checking and policy enforcement toolset, including an optional PAM module (pam_passwdqc), command-line programs (pwqcheck, pwqfilter, and pwqgen), and a library (libpasswdqc). On systems with PAM, pam_passwdqc is normally invoked on password changes by programs such as passwd(1). It is capable of checking password or passphrase strength, enforcing a policy, and offering randomly-generated passphrases, with all of these features being optional and easily (re-)configurable.
We also need to install pam_pwquality - PAM module to perform password quality checking.
- This module can be plugged into the password stack of a given service to provide some plug-in strength-checking for passwords. The code was originally based on pam_cracklib module and the module is backwards compatible with its options.
- The action of this module is to prompt the user for a password and check its strength against a system dictionary and a set of rules for identifying poor choices.
- The first action is to prompt for a single password, check its strength and then, if it is considered strong, prompt for the password a second time (to verify that it was typed correctly on the first occasion). All being well, the password is passed on to subsequent modules to be installed as the new authentication token.
sudo apt install libpam-pwquality
sudo apt-get install cracklib-runtime
sudo apt install libpwquality-tools
Changes to Original System Default files¶
/etc/pam.d/common-account
#
# /etc/pam.d/common-account - authorization settings common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of the authorization modules that define
# the central access policy for use on the system. The default is to
# only deny service to users whose accounts are expired in /etc/shadow.
#
# As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
# To take advantage of this, it is recommended that you configure any
# local modules either before or after the default block, and use
# pam-auth-update to manage selection of other modules. See
# pam-auth-update(8) for details.
#
# here are the per-package modules (the "Primary" block)
account [success=1 new_authtok_reqd=done default=ignore] pam_unix.so
# here's the fallback if no module succeeds
account requisite pam_deny.so
# prime the stack with a positive return value if there isn't one already;
# this avoids us returning an error just because nothing sets a success code
# since the modules above will each just jump around
account required pam_permit.so
# and here are more per-package modules (the "Additional" block)
# end of pam-auth-update config
account required pam_faillock.so
/etc/pam.d/common-auth
#
# /etc/pam.d/common-auth - authentication settings common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of the authentication modules that define
# the central authentication scheme for use on the system
# (e.g., /etc/shadow, LDAP, Kerberos, etc.). The default is to use the
# traditional Unix authentication mechanisms.
#
# As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
# To take advantage of this, it is recommended that you configure any
# local modules either before or after the default block, and use
# pam-auth-update to manage selection of other modules. See
# pam-auth-update(8) for details.
# here are the per-package modules (the "Primary" block)
auth required pam_faillock.so preauth audit deny=4 fail_interval=120 unlock_time=7200
auth [success=1 default=ignore] pam_unix.so nullok
# here's the fallback if no module succeeds
auth [default=die] pam_faillock.so authfail audit deny=4 fail_interval=120 unlock_time=7200
auth sufficient pam_faillock.so authsucc audit deny=4 fail_interval=120 unlock_time=7200
auth requisite pam_deny.so
# prime the stack with a positive return value if there isn't one already;
# this avoids us returning an error just because nothing sets a success code
# since the modules above will each just jump around
auth required pam_permit.so
# and here are more per-package modules (the "Additional" block)
# end of pam-auth-update config
/etc/pam.d/common-password
#
# /etc/pam.d/common-password - password-related modules common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of modules that define the services to be
# used to change user passwords. The default is pam_unix.
# Explanation of pam_unix options:
# The "yescrypt" option enables
#hashed passwords using the yescrypt algorithm, introduced in Debian
#11. Without this option, the default is Unix crypt. Prior releases
#used the option "sha512"; if a shadow password hash will be shared
#between Debian 11 and older releases replace "yescrypt" with "sha512"
#for compatibility . The "obscure" option replaces the old
#`OBSCURE_CHECKS_ENAB' option in login.defs. See the pam_unix manpage
#for other options.
# As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
# To take advantage of this, it is recommended that you configure any
# local modules either before or after the default block, and use
# pam-auth-update to manage selection of other modules. See
# pam-auth-update(8) for details.
# here are the per-package modules (the "Primary" block)
password requisite pam_pwquality.so retry=5 minlen=10 difok=3 lcredit=-2 ucredit=-2 dcredit=-1 ocredit=-1
password requisite pam_pwhistory.so remember=8 use_authok
password [success=1 default=ignore] pam_unix.so obscure use_authok try_first_pass yescrypt rounds=8
# here's the fallback if no module succeeds
password requisite pam_deny.so
# prime the stack with a positive return value if there isn't one already;
# this avoids us returning an error just because nothing sets a success code
# since the modules above will each just jump around
password required pam_permit.so
# and here are more per-package modules (the "Additional" block)
# end of pam-auth-update config
/etc/pam.d/common-sshd
# PAM configuration for the Secure Shell service
# Standard Un*x authentication.
@include common-auth
# Disallow non-root logins when /etc/nologin exists.
account required pam_nologin.so
# Uncomment and edit /etc/security/access.conf if you need to set complex
# access limits that are hard to express in sshd_config.
# account required pam_access.so
# Standard Un*x authorization.
@include common-account
# SELinux needs to be the first session rule. This ensures that any
# lingering context has been cleared. Without this it is possible that a
# module could execute code in the wrong domain.
session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so close
# Set the loginuid process attribute.
session required pam_loginuid.so
# Create a new session keyring.
session optional pam_keyinit.so force revoke
# Standard Un*x session setup and teardown.
@include common-session
# Print the message of the day upon successful login.
# This includes a dynamically generated part from /run/motd.dynamic
# and a static (admin-editable) part from /etc/motd.
session optional pam_motd.so motd=/run/motd.dynamic
session optional pam_motd.so noupdate
# Print the status of the user's mailbox upon successful login.
session optional pam_mail.so standard noenv # [1]
# Set up user limits from /etc/security/limits.conf.
session required pam_limits.so
# Read environment variables from /etc/environment and
# /etc/security/pam_env.conf.
session required pam_env.so # [1]
# In Debian 4.0 (etch), locale-related environment variables were moved to
# /etc/default/locale, so read that as well.
session required pam_env.so user_readenv=1 envfile=/etc/default/locale
# SELinux needs to intervene at login time to ensure that the process starts
# in the proper default security context. Only sessions which are intended
# to run in the user's context should be run after this.
session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so open
# Standard Un*x password updating.
@include common-password
Original System Default files for Reference¶
/etc/pam.d/common-account
#
# /etc/pam.d/common-account - authorization settings common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of the authorization modules that define
# the central access policy for use on the system. The default is to
# only deny service to users whose accounts are expired in /etc/shadow.
#
# As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
# To take advantage of this, it is recommended that you configure any
# local modules either before or after the default block, and use
# pam-auth-update to manage selection of other modules. See
# pam-auth-update(8) for details.
#
# here are the per-package modules (the "Primary" block)
account [success=1 new_authtok_reqd=done default=ignore] pam_unix.so
# here's the fallback if no module succeeds
account requisite pam_deny.so
# prime the stack with a positive return value if there isn't one already;
# this avoids us returning an error just because nothing sets a success code
# since the modules above will each just jump around
account required pam_permit.so
# and here are more per-package modules (the "Additional" block)
# end of pam-auth-update config
/etc/pam.d/common-auth
#
# /etc/pam.d/common-auth - authentication settings common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of the authentication modules that define
# the central authentication scheme for use on the system
# (e.g., /etc/shadow, LDAP, Kerberos, etc.). The default is to use the
# traditional Unix authentication mechanisms.
#
# As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
# To take advantage of this, it is recommended that you configure any
# local modules either before or after the default block, and use
# pam-auth-update to manage selection of other modules. See
# pam-auth-update(8) for details.
# here are the per-package modules (the "Primary" block)
auth [success=1 default=ignore] pam_unix.so nullok
# here's the fallback if no module succeeds
auth requisite pam_deny.so
# prime the stack with a positive return value if there isn't one already;
# this avoids us returning an error just because nothing sets a success code
# since the modules above will each just jump around
auth required pam_permit.so
# and here are more per-package modules (the "Additional" block)
auth optional pam_cap.so
# end of pam-auth-update config
/etc/pam.d/common-password
#
# /etc/pam.d/common-password - password-related modules common to all services
#
# This file is included from other service-specific PAM config files,
# and should contain a list of modules that define the services to be
# used to change user passwords. The default is pam_unix.
# Explanation of pam_unix options:
# The "yescrypt" option enables
#hashed passwords using the yescrypt algorithm, introduced in Debian
#11. Without this option, the default is Unix crypt. Prior releases
#used the option "sha512"; if a shadow password hash will be shared
#between Debian 11 and older releases replace "yescrypt" with "sha512"
#for compatibility . The "obscure" option replaces the old
#`OBSCURE_CHECKS_ENAB' option in login.defs. See the pam_unix manpage
#for other options.
# As of pam 1.0.1-6, this file is managed by pam-auth-update by default.
# To take advantage of this, it is recommended that you configure any
# local modules either before or after the default block, and use
# pam-auth-update to manage selection of other modules. See
# pam-auth-update(8) for details.
# here are the per-package modules (the "Primary" block)
password [success=1 default=ignore] pam_unix.so obscure yescrypt
# here's the fallback if no module succeeds
password requisite pam_deny.so
# prime the stack with a positive return value if there isn't one already;
# this avoids us returning an error just because nothing sets a success code
# since the modules above will each just jump around
password required pam_permit.so
# and here are more per-package modules (the "Additional" block)
# end of pam-auth-update config
/etc/pam.d/common-sshd
# PAM configuration for the Secure Shell service
# Standard Un*x authentication.
@include common-auth
# Disallow non-root logins when /etc/nologin exists.
account required pam_nologin.so
# Uncomment and edit /etc/security/access.conf if you need to set complex
# access limits that are hard to express in sshd_config.
# account required pam_access.so
# Standard Un*x authorization.
@include common-account
# SELinux needs to be the first session rule. This ensures that any
# lingering context has been cleared. Without this it is possible that a
# module could execute code in the wrong domain.
session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so close
# Set the loginuid process attribute.
session required pam_loginuid.so
# Create a new session keyring.
session optional pam_keyinit.so force revoke
# Standard Un*x session setup and teardown.
@include common-session
# Print the message of the day upon successful login.
# This includes a dynamically generated part from /run/motd.dynamic
# and a static (admin-editable) part from /etc/motd.
session optional pam_motd.so motd=/run/motd.dynamic
session optional pam_motd.so noupdate
# Print the status of the user's mailbox upon successful login.
session optional pam_mail.so standard noenv # [1]
# Set up user limits from /etc/security/limits.conf.
session required pam_limits.so
# Read environment variables from /etc/environment and
# /etc/security/pam_env.conf.
session required pam_env.so # [1]
# In Debian 4.0 (etch), locale-related environment variables were moved to
# /etc/default/locale, so read that as well.
session required pam_env.so user_readenv=1 envfile=/etc/default/locale
# SELinux needs to intervene at login time to ensure that the process starts
# in the proper default security context. Only sessions which are intended
# to run in the user's context should be run after this.
session [success=ok ignore=ignore module_unknown=ignore default=bad] pam_selinux.so open
# Standard Un*x password updating.
@include common-password