PAM.CONF(5) File Formats and Configurations PAM.CONF(5)
NAME
pam.conf - configuration file for pluggable authentication modules
SYNOPSIS
/etc/pam.confDESCRIPTION
pam.conf is the configuration file for the Pluggable Authentication
Module architecture, or
PAM. A
PAM module provides functionality for one
or more of four possible services: authentication, account management,
session management, and password management.
authentication service module Provides functionality to authenticate a user and set up user
credentials.
account management module Provides functionality to determine if the current user's account is
valid. This includes checking for password and account expiration,
as well as verifying access hour restrictions.
session management module Provides functionality to set up and terminate login sessions.
password management module Provides functionality to change a user's authentication token or
password.
Each of the four service modules can be implemented as a shared library
object which can be referenced in the
pam.conf configuration file.
Simplified pam.conf Configuration File The
pam.conf file contains a listing of services. Each service is paired
with a corresponding service module. When a service is requested, its
associated module is invoked. Each entry may be a maximum of 256
characters, including the end of line, and has the following format:
service_name module_type control_flag module_path options The following is an example of a
pam.conf configuration file with support
for authentication, account management, session management and password
management modules (See the
pam.conf file that is shipped with your
system for the contents of this file):
login auth requisite pam_authtok_get.so.1
login auth required pam_dhkeys.so.1
login auth required pam_unix_auth.so.1
login auth required pam_dial_auth.so.1
other account requisite pam_roles.so.1
other account required pam_unix_account.so.1
other session required pam_unix_session.so.1
other password required pam_dhkeys.so.1
other password requisite pam_authtok_get.so.1
other password requisite pam_authtok_check.so.1
other password required pam_authtok_store.so.1
service_name denotes the service (for example,
login,
dtlogin, or
rlogin).
The keyword, "
other," indicates the module that all other applications
which have not been specified should use. The "
other" keyword can also be
used if all services of the same
module_type have the same requirements.
In the example, since all of the services use the same session module,
they could have been replaced by a single
other line.
module_type denotes the service module type: authentication (
auth),
account management (
account), session management (
session), or password
management (
password).
The
control_flag field determines the behavior of stacking.
The
module_path field specifies the relative pathname to a shared library
object, or an included
PAM configuration file, which implements the
service functionality. If the pathname is not absolute, shared library
objects are assumed to be relative to
/usr/lib/security/$ISA/, and
included
PAM configuration files are assumed to be relative to
/usr/lib/security/.
The
ISA token is replaced by an implementation defined directory name
which defines the path relative to the calling program's instruction set
architecture.
The
options field is used by the
PAM framework layer to pass module
specific options to the modules. It is up to the module to parse and
interpret the options.
This field can be used by the modules to turn on debugging or to pass any
module specific parameters such as a
TIMEOUT value. The options supported
by the modules are documented in their respective manual pages.
Integrating Multiple Authentication Services With Stacking
When a
service_name of the same
module_type is defined more than once,
the service is said to be stacked. Each module referenced in the
module_path for that service is then processed in the order that it
occurs in the configuration file. The
control_flag field specifies the
continuation and failure semantics of the modules, and can contain one of
the following values:
binding If the service module returns success and no preceding
required modules returned failures, immediately return
success without calling any subsequent modules. If a
failure is returned, treat the failure as a
required module
failure, and continue to process the
PAM stack.
include Process the lines from the
PAM configuration file that is
specified in the
module_path at this point in the
PAM stack. The ``
other'' keyword is used if the specified
service_name is not found. 32 levels of included
PAM configuration files are supported. Any options are ignored.
optional If the service module returns success, record the success,
and continue to process the
PAM stack. If a failure is
returned, and it is the first
optional module failure, save
the failure code as an
optional failure. Continue to
process the
PAM stack.
required If the service module returns success, record the success,
and continue to process the
PAM stack. If a failure is
returned, and it is the first
required failure, save the
failure code as a
required failure. Continue to process
the
PAM stack.
requisite If the service module returns success, record the success,
and continue to process the
PAM stack. If a failure is
returned, immediately return the first non-optional failure
value recorded without calling any subsequent modules. That
is, return this failure unless a previous required service
module failed. If a previous required service module
failed, then return the first of those values.
sufficient If the service module return success and no preceding
required modules returned failures, immediately return
success without calling any subsequent modules. If a
failure is returned, treat the failure as an optional
module failure, and continue to process the
PAM stack.
If the
PAM stack runs to completion, that is, neither a
requisite module
failed, nor a
binding or
sufficient module success stops it, success is
returned if no required modules failed and at least one required,
requisite, optional module succeeded. If no module succeeded and a
required or binding module failed, the first of those errors is returned.
If no required or binding module failed and an optional module failed,
the first of the option module errors is returned. If no module in the
stack succeeded or failed, that is, all modules returned an ignore
status, a default error based on module type, for example, "User account
expired," is returned.
All errors in
pam.conf entries are logged to
syslog as
LOG_AUTH |
LOG_ERR errors. The use of a service with an error noted in the
pam.conf entry
for that service will fail. The system administrator will need to correct
the noted errors before that service may be used. If no services are
available or the
pam.conf file is missing, the system administrator may
enter system maintenance mode to correct or restore the file.
The following is a sample configuration file that stacks the
su,
login,
and
rlogin services.
su auth required pam_inhouse.so.1
su auth requisite pam_authtok_get.so.1
su auth required pam_dhkeys.so.1
su auth required pam_unix_auth.so.1
login auth requisite pam_authtok_get.so.1
login auth required pam_dhkeys.so.1
login auth required pam_unix_auth.so.1
login auth required pam_dial_auth.so.1
login auth optional pam_inhouse.so.1
rlogin auth sufficient pam_rhosts_auth.so.1
rlogin auth requisite pam_authtok_get.so.1
rlogin auth required pam_dhkeys.so.1
rlogin auth required pam_unix_auth.so.1
In the case of
su, the user is authenticated by the
inhouse and
authtok_get,
dhkeys, and
unix_auth authentication modules. Because the
inhouse and the other authentication modules are
required and
requisite,
respectively, an error is returned back to the application if any module
fails. In addition, if the
requisite authentication (
pam_authtok_get authentication) fails, the other authentication modules are never
invoked, and the error is returned immediately back to the application.
In the case of
login, the
required keyword for
control_flag requires that
the user be allowed to login only if the user is authenticated by all the
service modules. If
pam_unix_auth authentication fails, control continues
to proceed down the stack, and the
inhouse authentication module is
invoked.
inhouse authentication is optional by virtue of the optional
keyword in the
control_flag field. The user can still log in even if
inhouse authentication fails, assuming the modules stacked above
succeeded.
In the case of
rlogin, the
sufficient keyword for
control_flag specifies
that if the
rhosts authentication check succeeds, then
PAM should return
success to
rlogin and
rlogin should not prompt the user for a password.
The other authentication modules, which are in the stack, will only be
invoked if the
rhosts check fails. This gives the system administrator
the flexibility to determine if
rhosts alone is sufficient enough to
authenticate a remote user.
Some modules return
PAM_IGNORE in certain situations. In these cases the
PAM framework ignores the entire entry in
pam.conf regardless of whether
or not it is
binding,
requisite,
required,
optional, or
sufficient.
Utilities and Files
The specific service names and module types for each service should be
documented in the man page for that service. For instance, the
sshd(8) man page lists all of the
PAM service names and module types for the
sshd command.
The
PAM configuration file does not dictate either the name or the
location of the service specific modules. The convention, however, is the
following:
pam_module_name.so.x File that implements various function of
specific authentication services. As the
relative pathname specified,
/usr/lib/security/$ISA is prepended to it.
/etc/pam.conf Configuration file
/usr/lib/$ISA/libpam.so.1 File that implements the
PAM framework
library
EXAMPLES
Example 1: Using the include control flag
The following example collects the common Unix modules into a single file
to be included as needed in the example of a
pam.conf file. The common
Unix module file is named
unix_common and consists of:
OTHER auth requisite pam_authtok_get.so.1
OTHER auth required pam_dhkeys.so.1
OTHER auth required pam_unix_auth.so.1
OTHER auth required pam_unix_cred.so.1
OTHER account requisite pam_roles.so.1
OTHER account required pam_unix_account.so.1
OTHER session required pam_unix_session.so.1
OTHER password required pam_dhkeys.so.1
OTHER password requisite pam_authtok_get.so.1
OTHER password requisite pam_authtok_check.so.1
OTHER password required pam_authtok_store.so.1
The
pam.conf file and consists of:
# Authentication management
#
# login service (explicit because of pam_dial_auth)
#
login auth include unix_common
login auth required pam_dial_auth.so.1
#
# rlogin service (explicit because of pam_rhost_auth)
#
rlogin auth sufficient pam_rhosts_auth.so.1
rlogin auth include unix_common
#
# Default definitions for Authentication management
# Used when service name is not explicitly mentioned
#
OTHER auth include unix_common
#
# Default definition for Account management
# Used when service name is not explicitly mentioned
#
OTHER account include unix_common
#
# Default definition for Session management
# Used when service name is not explicitly mentioned
#
OTHER session include unix_common
#
# Default definition for Password management
# Used when service name is not explicitly mentioned
#
OTHER password include unix_common
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | See Below. |
+--------------------+-----------------+
The format is Stable. The contents has no stability attributes.
SEE ALSO
login(1),
passwd(1),
syslog(3C),
libpam(3LIB),
pam(3PAM),
attributes(7),
environ(7),
pam_authtok_check(7),
pam_authtok_get(7),
pam_authtok_store(7),
pam_dhkeys(7),
pam_krb5(7),
pam_passwd_auth(7),
pam_unix_account(7),
pam_unix_auth(7),
pam_unix_session(7),
in.rlogind(8),
in.rshd(8),
in.telnetd(8),
in.uucpd(8),
init(8),
sac(8),
su(8),
ttymon(8)NOTES
The
pam_unix module is no longer supported. Similar functionality is
provided by
pam_authtok_check(7),
pam_authtok_get(7),
pam_authtok_store(7),
pam_dhkeys(7),
pam_passwd_auth(7),
pam_unix_account(7),
pam_unix_auth(7), and
pam_unix_session(7).
With the removal of the
pam_unix module, the SunOS delivered PAM service
modules no longer need or support the "
use_first_pass" or
"
try_first_pass" options. This functionality is provided by stacking
pam_authtok_get(7) above a module that requires a password.
March 4, 2017
PAM.CONF(5)