PAM Configuration (Reference)

System applications, like ssh, that use the PAM service are configured in the PAM configuration files. See the pam.conf(4) man page for more information. These configuration files include the /etc/pam.conf file, as well as service specific files placed in /etc/pam.d. Changes to these files affect all users on the system. The service specific PAM configuration files are the preferred mechanism for configuring PAM, since their granularity means a mistake in a file only affects that service. Also, adding new PAM services is simplified to copying a single file. The service specific files allow for better interoperability with other cross-platform PAM applications, since /etc/pam.d is the default configuration in most PAM implementations.

In addition, PAM policy files can be used to create authentication policies for individual services and assign those policies either to an individual, a group of individuals, or all users, as needed. The default PAM policy files are located in /etc/security/pam_policy. The PAM policy files provide the ability to set or change the authentication policy for one or more users in a safe and reliable manner.

The system administrator manages the PAM configuration files. An incorrect order of entries in these files can cause unforeseen side effects. For example, a badly configured file can lock out users so that single-user mode becomes necessary for repair. For a description of setting the order, see How PAM Stacking Works.

PAM Configuration Search Order

The PAM configuration information in the PAM configuration files is collected by the PAM library in the following order:

1. The service name is looked for in /etc/pam.conf.

2. /etc/pam.d/service is checked.

3. The service name other is checked in /etc/pam.conf.

4. The /etc/pam.d/other file is checked.

This order allows for an existing /etc/pam.conf file to work with the per-service PAM configuration files located in /etc/pam.d.

PAM Configuration File Syntax

The /etc/pam.conf file and the PAM policy files use a syntax that is different than the service specific files. The syntax of each of these files is described below.

The entries in /etc/pam.conf or in PAM policy files are in one of the following formats:

service-name module-type control-flag module-path module-options

service-name module-type include path-to-included-PAM-configuration

service-name

The case insensitive name of the service, for example, login or passwd. An application can use different service names for the services that the application provides. For example, the Oracle Solaris secure shell daemon uses these service names: sshd-none, sshd-password, sshd-kbdint, sshd-pubkey, and sshd-hostbased.

The service name other is a predefined name that is used as a wildcard service-name. If a particular service-name is not found in the configuration file, the configuration for other is used.

module-type

The type of service, that is, auth, account, session, or password.

control-flag

Indicates the role of the module in determining the integrated success or failure value for the service. Valid control flags are binding, definitive, include, optional, required, requisite, and sufficient. See How PAM Stacking Works for information on the use of these flags.

module-path

The path to the library object that implements the service. If the pathname is not absolute, the pathname is assumed to be relative to /usr/lib/security/$ISA/. Use the architecture-dependent macro $ISA to cause libpam to look in the directory for the particular architecture of the application.

module-options

Options that are passed to the service modules. A module's man page describes the options that are accepted by that module. Typical module options include nowarn and debug.

path-to-included-PAM-configuration

Gives the full path to a separate PAM configuration file or a path name relative to the /usr/lib/security directory.

The per-service configuration files located in /etc/pam.d use the same syntax as pam.conf, but don't include the service name. When using the per-service configuration files, the name of the file is the service name. For instance, /etc/pam.d/cron includes the PAM configuration for the cron command.

Per User Authentication Policy

The pam_user_policy PAM module allows system administrators to specify PAM configurations on a per-user basis. The pam_policy key for the user needs to provide the path to a user-specific PAM configuration file. See the pam_user_policy(5) man page for more information.

Here are some ways to establish a per-user authentication policy:

• Create a new PAM policy file for a user and then use the usermod command to assign the policy to the user. This procedure is documented in How to Assign a Customized PAM Policy to a User.

• Use the usermod command to assign a pre-defined policy to a user.

• Assign a rights profile that includes a pam_policy key to a user using the -P option to the usermod command.

• Assign a rights profile that includes a pam_policy key to all users by adding it to the PROFS_GRANTED key in /etc/security/policy.conf. This procedure is documented in How to Assign a New Rights Policy to All Users

How PAM Stacking Works

When an application calls one of the following functions, libpam reads the PAM configuration files to determine which modules participate in the operation for this service:

• pam_authenticate(3PAM)

• pam_acct_mgmt(3PAM)

• pam_setcred(3PAM)

• pam_open_session(3PAM)

• pam_close_session(3PAM)

• pam_chauthtok(3PAM)

If the configuration files contain only one module for an operation for this service such as authentication or account management, the result of that module determines the outcome of the operation. For example, the default authentication operation for the passwd application contains one module, pam_passwd_auth.so.1:

passwd  auth required           pam_passwd_auth.so.1

If, on the other hand, there are multiple modules defined for the service's operation, those modules are said to be stacked and that a PAM stack exists for that service. For example, consider the case where /etc/pam.d/login contains the following entries:

auth definitive         pam_user_policy.so.1
auth requisite          pam_authtok_get.so.1
auth required           pam_unix_auth.so.1
auth required           pam_dhkeys.so.1
auth required           pam_unix_cred.so.1

auth required           pam_dial_auth.so.1

These entries represent a sample auth stack for the login service. To determine the outcome of this stack, the result codes of the individual modules require an integration process. In the integration process, the modules are executed in order as specified in the file. Each success or failure code is integrated in the overall result depending on the module's control flag. The control flag can cause early termination of the stack. For example, a requisite or definitive module might fail, or a sufficient, definitive, or binding module might succeed. After the stack has been processed, the individual results are combined into a single, overall result that is delivered to the application.

The control flag indicates the role that a PAM module plays in determining access to the service. The control flags and their effects are:

• Binding – Success in meeting a binding module's requirements returns success immediately to the application if no previous required modules have failed. If these conditions are met, then no further execution of modules occurs. Failure causes a required failure to be recorded and the processing of modules to be continued.

• Definitive – Success in meeting a definitive module's requirements returns success immediately to the application if no previous required modules have failed. If a previous required module failed, that failure is immediately returned to the application with no further execution of modules. Failure results in an immediate error return with no further execution of modules.

• Include – Adds lines from a separate PAM configuration file to be used at this point in the PAM stack. This flag does not control success or failure behaviors. When a new file is read, the PAM include stack is incremented. When the stack check in the new file finishes, the include stack value is decremented. When the end of a file is reached and the PAM include stack is 0, then the stack processing ends. The maximum number for the PAM include stack is 32.

• Optional – Success in meeting an optional module's requirements is not necessary for using the service. Failure causes an optional failure to be recorded.

• Required – Success in meeting a required module's requirements is necessary for using the service. Failure results in an error return after the remaining modules for this service have been executed. Final success for the service is returned only if no binding or required modules have reported failures.

• Requisite – Success in meeting a requisite module's requirements is necessary for using the service. Failure results in an immediate error return with no further execution of modules. All requisite modules for a service must return success for the function to be able to return success to the application.

• Sufficient – If no previous required failures have occurred, success in a sufficient module returns success to the application immediately with no further execution of modules. Failure causes an optional failure to be recorded.

The following two diagrams shows how access is determined in the integration process. The first diagram indicates how success or failure is recorded for each type of control flag. The second diagram shows how the integrated value is determined.

Figure 14-2 PAM Stacking: Effect of Control Flags

Figure 14-3 PAM Stacking: How Integrated Value Is Determined

PAM Stacking Example

This example shows the default definitions for authentication management in the /etc/pam.d/other file. These definitions are used if no service-specific definitions have been configured.

#
# Default definitions for Authentication management
# Used when service name is not explicitly mentioned for authentication
#
auth definitive         pam_user_policy.so.1
auth requisite          pam_authtok_get.so.1
auth required           pam_dhkeys.so.1
auth required           pam_unix_auth.so.1
auth required           pam_unix_cred.so.1 

First, the security policy for the user is checked using the pam_user_policy module. The definitive control flag selects that if the evaluation of the security policy succeeds, the service returns success to the application, since no other modules have been checked at this point. If the request fails, then a failure message is sent to the application and no further checking is done. If no policy is set for the user, then the next module is executed.

If a per-user PAM policy isn't specified for this user, then the pam_authtok_get module is executed. The control flag for this module is set to requisite. If pam_authtok_get fails, then the authentication process ends and the failure is returned to the service.

If pam_authtok_get does not fail, then the next three modules are executed. These modules are configured with the required control flag, so that the process continues regardless of whether an individual failure is returned. After pam_unix_cred is executed, no modules remain. At this point, if all the modules succeeded, the user is granted access. If either pam_dhkeys, pam_unix_auth, or pam_unix_cred has returned a failure, the user is denied access.