2 Authentication with PAM #
Linux uses PAM (pluggable authentication modules) in the authentication process as a layer that mediates between user and application. PAM modules are available on a system-wide basis, so they can be requested by any application. This chapter describes how the modular authentication mechanism works and how it is configured.
2.1 What is PAM? #
System administrators and programmers often want to restrict access to certain parts of the system or to limit the use of certain functions of an application. Without PAM, applications must be adapted every time a new authentication mechanism, such as LDAP, Samba, or Kerberos, is introduced. However, this process is time-consuming and error-prone. One way to avoid these drawbacks is to separate applications from the authentication mechanism and delegate authentication to centrally managed modules. Whenever a newly required authentication scheme is needed, it is sufficient to adapt or write a suitable PAM module for use by the program in question.
The PAM concept consists of:
PAM modules, which are a set of shared libraries for a specific authentication mechanism.
A module stack with of one or more PAM modules.
A PAM-aware service which needs authentication by using a module stack or PAM modules. Usually a service is a familiar name of the corresponding application, like
login
orsu
. The service nameother
is a reserved word for default rules.Module arguments, with which the execution of a single PAM module can be influenced.
A mechanism evaluating each result of a single PAM module execution. A positive value executes the next PAM module. The way a negative value is dealt with depends on the configuration: “no influence, proceed” up to “terminate immediately” and anything in between are valid options.
2.2 Structure of a PAM configuration file #
PAM can be configured in two ways:
- File based configuration (
/etc/pam.conf
) The configuration of each service is stored in
/etc/pam.conf
. However, for maintenance and usability reasons, this configuration scheme is not used in SUSE Linux Enterprise Server.- Directory based configuration (
/etc/pam.d/
) Every service (or program) that relies on the PAM mechanism has its own configuration file in the
/etc/pam.d/
directory. For example, the service forsshd
can be found in the/etc/pam.d/sshd
file.
The files under /etc/pam.d/
define the PAM modules
used for authentication. Each file consists of lines, which define a
service, and each line consists of a maximum of four components:
TYPE CONTROL MODULE_PATH MODULE_ARGS
The components have the following meaning:
- TYPE
Declares the type of the service. PAM modules are processed as stacks. Different types of modules have different purposes. For example, one module checks the password, another verifies the location from which the system is accessed, and yet another reads user-specific settings. PAM knows about four different types of modules:
auth
Check the user's authenticity, traditionally by querying a password. However, this can also be achieved with a chip card or through biometrics (for example, fingerprints or iris scan).
account
Modules of this type check if the user has general permission to use the requested service. As an example, such a check should be performed to ensure that no one can log in with the user name of an expired account.
password
The purpose of this type of module is to enable the change of an authentication token. Usually this is a password.
session
Modules of this type are responsible for managing and configuring user sessions. They are started before and after authentication to log login attempts and configure the user's specific environment (mail accounts, home directory, system limits, etc.).
- CONTROL
Indicates the behavior of a PAM module. Each module can have the following control flags:
required
A module with this flag must be successfully processed before the authentication may proceed. After the failure of a module with the
required
flag, all other modules with the same flag are processed before the user receives a message about the failure of the authentication attempt.requisite
Modules having this flag must also be processed successfully, in much the same way as a module with the
required
flag. However, in case of failure a module with this flag gives immediate feedback to the user and no further modules are processed. In case of success, other modules are subsequently processed, like any modules with therequired
flag. Therequisite
flag can be used as a basic filter checking for the existence of certain conditions that are essential for a correct authentication.sufficient
After a module with this flag has been successfully processed, the requesting application receives an immediate message about the success and no further modules are processed, provided there was no preceding failure of a module with the
required
flag. The failure of a module with thesufficient
flag has no direct consequences, in the sense that any subsequent modules are processed in their respective order.optional
The failure or success of a module with this flag does not have any direct consequences. This can be useful for modules that are only intended to display a message (for example, to tell the user that mail has arrived) without taking any further action.
include
If this flag is given, the file specified as argument is inserted at this place.
- MODULE_PATH
Contains a full file name of a PAM module. It does not need to be specified explicitly, as long as the module is located in the default directory
/lib/security
(for all 64-bit platforms supported by SUSE® Linux Enterprise Server, the directory is/lib64/security
).- MODULE_ARGS
Contains a space-separated list of options to influence the behavior of a PAM module, such as
debug
(enables debugging) ornullok
(allows the use of empty passwords).
In addition, there are global configuration files for PAM modules under
/etc/security
, which define the exact behavior of
these modules (examples include pam_env.conf
and
time.conf
). Every application that uses a PAM module
actually calls a set of PAM functions, which then process the information
in the various configuration files and return the result to the
requesting application.
To simplify the creation and maintenance of PAM modules, common default
configuration files for the types auth
,
account
, password
, and
session
modules have been introduced. These are
retrieved from every application's PAM configuration. Updates to the
global PAM configuration modules in common-*
are
thus propagated across all PAM configuration files without requiring the
administrator to update every single PAM configuration file.
The global PAM configuration files are maintained using the
pam-config
tool. This tool automatically adds new
modules to the configuration, changes the configuration of existing ones
or deletes modules (or options) from the configurations. Manual
intervention in maintaining PAM configurations is minimized or no longer
required.
When using a 64-bit operating system, it is possible to also include a runtime environment for 32-bit applications. In this case, make sure that you also install the 32-bit version of the PAM modules.
2.3 The PAM configuration of sshd #
Consider the PAM configuration of sshd as an example:
/etc/pam.d/sshd
) ##%PAM-1.0 1 auth requisite pam_nologin.so 2 auth include common-auth 3 account requisite pam_nologin.so 2 account include common-account 3 password include common-password 3 session required pam_loginuid.so 4 session include common-session 3 session optional pam_lastlog.so silent noupdate showfailed 5
Declares the version of this configuration file for PAM 1.0. This is merely a convention, but could be used in the future to check the version. | |
Checks, if | |
Refers to the configuration files of four module types:
| |
Sets the login UID process attribute for the process that was authenticated. | |
Displays information about the last login of a user. |
By including the configuration files instead of adding each module separately to the respective PAM configuration, you automatically get an updated PAM configuration when an administrator changes the defaults. Formerly, you needed to adjust all configuration files manually for all applications when changes to PAM occurred or a new application was installed. Now the PAM configuration is made with central configuration files and all changes are automatically inherited by the PAM configuration of each service.
The first include file (common-auth
) calls three
modules of the auth
type:
pam_env.so
,
pam_gnome_keyring.so
and
pam_unix.so
. See
Example 2.2, “Default configuration for the auth
section (common-auth
)”.
auth
section (common-auth
) #auth required pam_env.so 1 auth optional pam_gnome_keyring.so 2 auth required pam_unix.so try_first_pass 3
| |
| |
|
The whole stack of auth
modules is processed before
sshd
gets any feedback about
whether the login has succeeded. All modules of the stack having the
required
control flag must be processed successfully
before sshd
receives a message
about the positive result. If one of the modules is not successful, the
entire module stack is still processed and only then is
sshd
notified about the negative
result.
When all modules of the auth
type have been
successfully processed, another include statement is processed, in this
case, that in Example 2.3, “Default configuration for the account
section (common-account
)”.
common-account
contains only one module,
pam_unix
. If pam_unix
returns the
result that the user exists, sshd receives a message announcing this
success and the next stack of modules (password
) is
processed, shown in Example 2.4, “Default configuration for the password
section (common-password
)”.
account
section (common-account
) #account required pam_unix.so try_first_pass
password
section (common-password
) #password requisite pam_cracklib.so password optional pam_gnome_keyring.so use_authtok password required pam_unix.so use_authtok nullok shadow try_first_pass
Again, the PAM configuration of
sshd
involves only an include
statement referring to the default configuration for
password
modules located in
common-password
. These modules must successfully be
completed (control flags requisite
and
required
) whenever the application requests the change
of an authentication token.
Changing a password or another authentication token requires a security
check. This is achieved with the pam_cracklib
module. The pam_unix
module used afterward carries
over any old and new passwords from pam_cracklib
, so
the user does not need to authenticate again after changing the password.
This procedure makes it impossible to circumvent the checks carried out
by pam_cracklib
. Whenever the
account
or the auth
type are
configured to complain about expired passwords, the
password
modules should also be used.
session
section (common-session
) #session required pam_limits.so session required pam_unix.so try_first_pass session optional pam_umask.so session optional pam_systemd.so session optional pam_gnome_keyring.so auto_start only_if=gdm,gdm-password,lxdm,lightdm session optional pam_env.so
As the final step, the modules of the session
type
(bundled in the common-session
file) are called to
configure the session according to the settings for the user in question.
The pam_limits
module loads the file
/etc/security/limits.conf
, which may define limits
on the use of certain system resources. The pam_unix
module is processed again. The pam_umask
module can
be used to set the file mode creation mask. Since this module carries the
optional
flag, a failure of this module would not
affect the successful completion of the entire session module stack. The
session
modules are called a second time when the user
logs out.
2.4 Configuration of PAM modules #
Some PAM modules are configurable. The configuration files are
located in /etc/security
. This section briefly
describes the configuration files relevant to the sshd
example—pam_env.conf
and
limits.conf
.
2.4.1 pam_env.conf #
pam_env.conf
can be used to define a standardized
environment for users that is set whenever the
pam_env
module is called. With it, preset
environment variables using the following syntax:
VARIABLE [DEFAULT=VALUE] [OVERRIDE=VALUE]
- VARIABLE
Name of the environment variable to set.
[DEFAULT=<value>]
Default VALUE the administrator wants to set.
[OVERRIDE=<value>]
Values that may be queried and set by
pam_env
, overriding the default value.
A typical example of how pam_env
can be used is
the adaptation of the DISPLAY
variable, which is changed
whenever a remote login takes place. This is shown in
Example 2.6, “pam_env.conf”.
REMOTEHOST DEFAULT=localhost OVERRIDE=@{PAM_RHOST} DISPLAY DEFAULT=${REMOTEHOST}:0.0 OVERRIDE=${DISPLAY}
The first line sets the value of the REMOTEHOST
variable
to localhost
, which is used whenever
pam_env
cannot determine any other value. The
DISPLAY
variable in turn contains the value of
REMOTEHOST
. Find more information in the comments in
/etc/security/pam_env.conf
.
2.4.2 pam_mount.conf.xml #
The purpose of pam_mount
is to mount user home
directories during the login process, and to unmount them during logout
in an environment where a central file server keeps all the home
directories of users. With this method, it is not necessary to mount a
complete /home
directory where all the user home
directories would be accessible. Instead, only the home directory of the
user who is about to log in, is mounted.
After installing pam_mount
, a template for
pam_mount.conf.xml
is available in
/etc/security
. The description of the various
elements can be found in the manual page man 5
pam_mount.conf
.
A basic configuration of this feature can be done with YaST. Select See Section 20.5, “Configuring clients”.
› › to add the file server.
LUKS2 support was added to cryptsetup
2.0, and SUSE Linux Enterprise Server has included support for LUKS2 in
pam_mount
since SUSE Linux Enterprise Server 12 SP3.
2.4.3 limits.conf #
System limits can be set on a user or group basis in
limits.conf
, which is read by the
pam_limits
module. The file allows you to set
hard limits, which may not be exceeded, and soft limits, which
may be exceeded temporarily. For more information about the syntax and
the options, see the comments in
/etc/security/limits.conf
.
2.5 Configuring PAM using pam-config #
The pam-config
tool helps you configure the global PAM
configuration files (/etc/pam.d/common-*
) and
several selected application configurations. For a list of supported
modules, use the pam-config --list-modules
command.
Use the pam-config
command to maintain your PAM
configuration files. Add new modules to your PAM configurations, delete
other modules or modify options to these modules. When changing global
PAM configuration files, no manual tweaking of the PAM setup for
individual applications is required.
A simple use case for pam-config
involves the
following:
Auto-generate a fresh unix-style PAM configuration. Let pam-config create the simplest possible setup which you can extend later on. The
pam-config --create
command creates a simple Unix authentication configuration. Pre-existing configuration files not maintained by pam-config are overwritten, but backup copies are kept as*.pam-config-backup
.Add a new authentication method. Adding a new authentication method (for example, SSSD) to your stack of PAM modules comes down to a simple
pam-config --add --sss
command. SSSD is added wherever appropriate across allcommon-*-pc
PAM configuration files.Add debugging for test purposes. To make sure the new authentication procedure works as planned, turn on debugging for all PAM-related operations. The
pam-config --add --sss-debug
command turns on debugging for SSSD-related PAM operations. Find the debugging output in thesystemd
journal (see Kapitel 21,journalctl
: Abfragen dessystemd
-Journals). To configure SSSD, refer to Section 5.7, “Using SSSD to manage LDAP authentication”.Query your setup. Before you finally apply your new PAM setup, check if it contains all the options you wanted to add. The
pam-config --query --
MODULE command lists both the type and the options for the queried PAM module.Remove the debug options. Finally, remove the debug option from your setup when you are entirely satisfied with its performance. The
pam-config --delete --sss-debug
command turns off debugging for thepam_ssh.so
module. In case you had debugging options added for other modules, use similar commands to turn these off.
For more information on the pam-config
command and the
options available, refer to the manual page of
pam-config(8)
.
2.6 Manually configuring PAM #
If you prefer to manually create or maintain your PAM configuration
files, make sure to disable pam-config
for these
files.
When you create your PAM configuration files from scratch using the
pam-config --create
command, it creates symbolic links
from the common-*
to the
common-*-pc
files.
pam-config
only modifies the
common-*-pc
configuration
files. Removing these symbolic links effectively disables pam-config,
because pam-config only operates on the
common-*-pc
files and
these files are not put into effect without the symbolic links.
pam_systemd.so
in configuration
If you are creating your own PAM configuration, make sure to include
pam_systemd.so
configured as session
optional
. Not including the pam_systemd.so
can
cause problems with systemd
task limits. For details, refer to the man
page of pam_systemd.so
.
2.7 Configuring U2F keys for local login #
To provide more security during the local login , you can configure
two-factor authentication using the pam-u2f
framework and
the U2F feature on Yubikeys and Security Keys.
To set up U2F on your system, you need to associate your key with your account . After that, configure your system to use the key. The procedure is described in the following sections.
2.7.1 Associating the U2F key with your account #
To associate your U2F key with your account proceed as follows:
Log in to your machine.
Insert your U2F key.
Create a directory for the U2F key configuration:
>
sudo
mkdir -p ~/.config/YubicoRun the
pamu2fcfg
that outputs configuration lines:>
sudo
pamu2fcfg > ~/.config/Yubico/u2f_keysWhen your device begins flashing, touch the metal contact to confirm the association.
We recommend using a backup U2F device, which you can set up by running the following commands:
Run:
>
sudo
pamu2fcfg -n >> ~/.config/Yubico/u2f_keysWhen your device begins flashing, touch the metal contact to confirm the association.
You can move the output file from the default location to a directory that
requires the sudo
permission to modify the file to
increase security, for example, to the /etc
directory.
To do so, follow the steps:
Create a directory in
/etc
:>
sudo
mkdir /etc/YubicoMove the created file:
>
sudo
mv ~/.config/Yubico/u2f_keys /etc/Yubico/u2f_keys
u2f_keys
to a non-default location
If you move the output file to a different directory than is the default
($HOME/.config/Yubico/u2f_keys
), you need to add the
path to the /etc/pam.d/login
file as described in
Section 2.7.2, “Updating the PAM configuration”.
2.7.2 Updating the PAM configuration #
After you have created the U2F keys configuration, you need to adjust the PAM configuration on your system.
Open the file
/etc/pam.d/login
.Add the line
auth required pam_u2f.so
to the file as follows:#%PAM-1.0 auth include common-auth auth required pam_u2f.so account include common-account password include common-password session optional pam_keyinit.so revoke session include common-session #session optional pam_xauth.so
If you placed the
u2f_keys
file to a different location than$HOME/.config/Yubico/u2f_keys
, you need to use theauthfile
option in the/etc/pam.d/login
PAM file as follows:#%PAM-1.0 auth requisite pam_nologin.so auth include common-auth auth required pam_u2f.so authfile=<PATH_TO_u2f_keys> ...
where <PATH_TO_u2f_keys> is the absolute path to the
u2f_keys
file.
2.8 More information #
In the /usr/share/doc/packages/pam
directory after
installing the pam-doc
package, find the
following additional documentation:
- READMEs
In the top level of this directory, there is the
modules
subdirectory holding README files about the available PAM modules.- The Linux-PAM System Administrators' Guide
This document comprises everything that the system administrator should know about PAM. It discusses a range of topics, from the syntax of configuration files to the security aspects of PAM.
- The Linux-PAM Module Writers' Manual
This document summarizes the topic from the developer's point of view, with information about how to write standard-compliant PAM modules.
- The Linux-PAM Application Developers' Guide
This document comprises everything needed by an application developer who wants to use the PAM libraries.
- The PAM manual pages
PAM in general and the individual modules come with manual pages that provide a good overview of the functionality of all the components.