PAM Configuration Reference

Language:

This section provides additional details about PAM, including PAM stacking.

PAM Configuration Files

System applications, such as login and ssh, that use the PAM framework are configured in the PAM configuration files in the /etc/pam.d directory. The /etc/pam.conf file can also be used. Changes to these files affect all users on the system.

Additionally, the /etc/security/pam_policy directory holds PAM configuration files. These files cover multiple services and are designed for per-user assignment. Files in this directory must not be modified.

/etc/pam.d directory – Contains service-specific PAM configuration files, including the wildcard file, other. To add a service for an application, add a single service-name file that is the service name used by the application. If appropriate, your application can use the PAM stack in the other file.

The service files in the /etc/pam.d directory provide the default configuration in most PAM implementations. They are self-assembled by using the IPS mechanism as described in the pkg(5) man page. This default simplifies interoperability with other cross-platform PAM applications. For more information, see the pam.conf(4) man page.
/etc/pam.conf file – The legacy PAM configuration and policy file. This file is delivered empty. The preferred mechanism for configuring PAM is to use the files in the /etc/pam.d directory. For more information, see the pam.conf(4) man page.
/etc/security/pam_policy directory – Contains PAM policy files that contain policies for multiple services. These files can be assigned to an individual, to a group of individuals, or to all users, as needed. Such an assignment overrides the system PAM configuration files in pam.conf or the /etc/pam.d directory. Do not modify these files. To add a per-user file, see How to Create a Site-Specific PAM Configuration File. For information about per-user files, see the pam_user_policy(5) man page.

The security administrator manages all PAM configuration files. An incorrect order of entries, that is, an incorrect PAM stack, can cause unforeseen side effects. For example, a badly configured file might lock out users so that single-user mode becomes necessary for repair. For assistance, see PAM Stacking and How to Troubleshoot PAM Configuration Errors.

PAM Configuration Search Order

Application calls to the PAM framework search for the configured PAM services in the following order:

The service name is looked up in the /etc/pam.conf file.
Specific services are used in the /etc/pam.d/service-name file.
The service name other is checked in the /etc/pam.conf file.
The /etc/pam.d/other file is used.

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

Note - If an unknown option is passed in, for example, a misspelled module name, an error is logged in syslog and the option is ignored.

PAM Configuration File Syntax

The pam.conf file and the PAM per-user files use a syntax that is different from the service-specific files in the pam.d directory.

The entries in the /etc/pam.conf file and the /etc/security/pam_policy files are in one of two formats:

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

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

The entries in the service-name files in the /etc/pam.d directory omit the service name. The name of the file provides the service name.
```
module-type control-flag module-path module-options
```
```
module-type include path-to-included-PAM-configuration
```

The PAM configuration file syntax items are as follows:

service-name

The case-insensitive name of the service, for example, login or ssh. An application can use different service names for the services that the application provides. For example, search for the word PAM in the sshd(1M) man page for the service names for the different services that the sshd daemon provides.

The predefined service name "other" is the default service name if no specific service configuration is provided.

module-type

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

control-flag

Indicates the role of the module in determining the success or failure value for the service. Valid control flags are described in PAM Stacking.

module-path

The path to the module that implements the module type. If the pathname is not absolute, it is assumed to be relative to the path /usr/lib/security/$ISA/. The $ISA macro or token directs the PAM framework to look in the module path's architecture-specific directory.

module-options

Options such as nowarn and debug that can be passed to the service modules. A module's man page describes the options for that module.

path-to-included-PAM-configuration

Specifies the full path to a PAM configuration file or a file name that is relative to the /usr/lib/security directory.

PAM Stacking

When an application calls one of the following functions, the PAM framework reads the PAM configuration files to determine which modules implement this application's PAM service name:

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, 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, in the /etc/pam.d/passwd file.

auth required           pam_passwd_auth.so.1

If, on the other hand, multiple modules implement a service, those modules are said to be stacked, that is, a PAM stack exists for that service name. For example, consider the entries in a sample /etc/pam.d/login service:

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 create an auth stack for the login service name. 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 their order in the file. Each success or failure code is integrated in to the overall result according to the module's control flag. The control flag can cause early termination of the stack. For example, the failure of a requisite or definitive module terminates the stack. If there are no previous failures, the success of a sufficient, definitive, or binding module also terminates the stack. After the stack is processed, the individual results are combined into a single, overall result that is delivered to the application. For a graphic view of the flow, see PAM Stacking: Effect of Control Flags and PAM Stacking: How Integrated Value Is Determined.

The control flag indicates the role that a PAM module plays in determining success or failure. 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 failures have been recorded. 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 failures have been recorded.

If a previous failure has been recorded, 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 the stack to succeed. Final success for the stack is returned only if no binding or required modules have reported failures.

Failure results in an error return after the remaining modules for this service have been executed.
Requisite – Success in meeting a requisite module's requirements is necessary for the stack to succeed. All requisite modules in the stack must return success for the stack to be able to return success to the application.

Failure results in an immediate error return with no further execution of modules.
Sufficient – If no previous required failures have been recorded, success in a sufficient module returns success immediately with no further execution of modules.

Failure causes an optional failure to be recorded.

The following two connected diagrams show how a result is determined in the integration process.

The first diagram shows how success or failure is recorded for each type of control flag. The results are shown in the second diagram.
The second diagram shows how the integrated value is determined. Optional failure and required failure return failure, and success returns success. The application determines how to handle these return codes.

Figure 2 PAM Stacking: Effect of Control Flags

image:Flow diagram shows how control flags affect PAM stacking.

Figure 3 PAM Stacking: How Integrated Value Is Determined

image:Flow diagram shows how integrated values are determined in PAM stacking.

PAM Stacking Example

The following example shows the default definitions for authentication management in a sample /etc/pam.d/other file. These definitions are used for authentication if no service-specific authentication 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 PAM policy for the user is checked by using the pam_user_policy.so module. The definitive control flag dictates that if the evaluation of the configured PAM stack succeeds, success is returned to the application, because no other modules have been checked at this point. If the evaluation of the configured PAM stack fails, then a failure code is returned to the application and no further checking is done. If no per-user PAM policy is assigned to this user, then the next module is executed.

If a per-user PAM policy is not assigned to 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 application.

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 integration 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, success is returned to the application. If any of pam_dhkeys, pam_unix_auth, or pam_unix_cred has returned a failure, failure is returned to the application.

PAM Service Modules

This section lists selected PAM service modules. The modules are listed by their man page followed by a brief description of where and when they are used. For more information, read the man page.

For a list of all PAM service modules that Oracle Solaris provides, see section 5 of the man pages. New modules are added on a regular basis. For example, in this release, a number of modules are added for authentication with Windows systems. Your site might also add PAM modules from third parties.

pam_allow(5)

Returns PAM_SUCCESS for all calls. See also the pam_deny(5) man page.

pam_authtok_check(5)

Validates the password token for password change.

pam_authtok_get(5)

Provides password prompting functionality to the PAM stack.

pam_authtok_store(5)

Updates the password token for PAM_USER.

pam_deny(5)

Returns the module type default failure return code for all calls. See also the pam_allow(5) man page.

pam_dhkeys(5)

Provides functionality to two PAM services: Secure RPC authentication and Secure RPC authentication token management.

pam_krb5(5)

Provides functions to verify the identity of a Kerberos user and to manage the Kerberos credentials cache.

pam_krb5_migrate(5)

Helps to migrate PAM_USER to the client's local Kerberos realm.

pam_ldap(5)

Provides functionality for the PAM authentication and account management stacks by the configured LDAP directory server.

pam_list(5)

Provides functions to validate the user's account on this host. The validation is based on a list of users and netgroups on the host.

pam_passwd_auth(5)

Provides authentication functionality to the password stack.

pam_pkcs11(5)

Enables a user to log in to a system by using an X.509 certificate and its dedicated private key that is stored in a PKCS#11 token.

pam_roles(5)

Verifies that a user is authorized to assume a role and prevents direct login by a role.

pam_smb_passwd(5)

Supports the changing or adding of SMB passwords for local Oracle Solaris users. See also the smb(4) man page.

pam_smbfs_login(5)

Synchronizes passwords between Oracle Solaris clients and their CIFS/SMB servers.

pam_tsol_account(5)

Verifies Trusted Extensions account limitations that are related to labels.

pam_tty_tickets(5)

Provides a mechanism for checking a ticket that was created by a prior successful authentication.

pam_unix_account(5)

Provides functions to validate that the user's account is not locked or expired and that the user's password does not need to be changed.

Includes checks of access_times and access_tz.

pam_unix_auth(5)

Provides functions to verify that the password is the correct password for PAM_USER.

pam_unix_cred(5)

Provides functions that establish user credential information. It enables the authentication functionality to be replaced independently from the credential functionality.

pam_unix_session(5)

Opens and closes a session, and also updates the /var/adm/lastlog file.

pam_user_policy(5)

Calls a user-specific PAM configuration.

pam_zfs_key(5)

Provides functions to load and change the ZFS encryption passphrase for a user's encrypted home directory.