The PAM system configuration file

The following parameters are available when configuring the IBM® Security Verify Gateway for Linux PAM and AIX PAM (Pluggable Authentication Modules).

On Linux®, all PAM-aware services have a file in /etc/pam.d with the same name as the service. For example, on Redhat 7 the sshd service file /etc/pam.d/sshd contains:
#%PAM-1.0
auth       required     pam_sepermit.so
auth       substack     password-auth
auth       include      postlogin
...
On AIX®, all PAM-aware services are in the /etc/pam.conf file. For example, on AIX 7.2 the /etc/pam.conf file contains:
#
# Authentication
#
authexec      auth     required      pam_aix
dtaction      auth     required      pam_aix
dtsession     auth     required      pam_aix
...
Each line is of the format:
module_interface control_flag module_name [module_arguments]
Note: The pound sign character (#) denotes the start of a comment in PAM configurations. This character can have unintended consequences on your configuration.

Module interface

Only the module_interface type of auth is supported by this pam_ibm_auth.so module.

Module name

The module name is pam_ibm_auth.so.

Module arguments

This example shows an entry for the PAM module with arguments.
auth sufficient pam_ibm_auth.so auth_method=choice-then-otp 
The following arguments are accepted by the pam_ibm_auth.so module.
Note: PAM requires that arguments be wrapped in square brackets if they contain a space. For example,
[otp-prompt=Enter OTP %C- ]
debug
This argument is a standard PAM module option. Use the syslog() call to log debugging information to the system log files.
nowarn
This argument is a standard PAM module option. The nowarn option disables the generation of warnings, including password expiration warnings.
ibm_auth_config={config-file}
If not specified, the default is /etc/pam_ibm_auth.json for Linux and UNIX systems. This file contains the IBM Auth API configuration that has the Verify server connection details. See The module configuration file.
auth_method={auth_method}
This argument is optional and defaults to TOTP validation. This argument specifies the method of authentication that is required to authenticate users. The following list of authentication methods includes some methods that accept a password first. Password in these methods refers to the Verify user password, not the UNIX password.
Note: If a password was supplied to a previously started PAM module, for example pam_unix.so, that password is used in any Verify auth methods that involve a password. If that previously supplied password and the Verify password do not match, the authentication fails. This issue is a known limitation.
Table 1. Acceptable values
Value Description
password Requires a valid Verify password.
password-and-totp A Verify password plus a TOTP value must be provided in a single value. You can configure whether the password or TOTP value is first in the value, and configure the character that is used to separate the two values. By default the format is TOTP:password.
password-then-totp A Verify password must be provided, and if successfully provided, a TOTP value is asked for and validated.
totp A TOTP value is asked for and validated.
password-then-smsotp A Verify password must be provided, and if successfully provided, an SMS message is sent to the user's registered mobile device with an OTP value. Then the PAM module requests the SMSOTP value from the user and validates it.
smsotp An SMS OTP validation is initiated and the SMS OTP value is asked for and validated.
password-then-emailotp A Verify password must be provided, and if successfully provided, an email message is sent to the user with an OTP value. The PAM module requests the EmailOTP value and validates it.
emailotp An email OTP validation is initiated and the PAM module requests the email OTP value and then validate it.
password-then-choice-then-otp A Verify password must be provided, and if successfully provided, the user is asked to choose of one of their OTP enrollments. After the choice is made, the OTP validation is initiated and the user is prompted for the OTP value.
Note:
  • If the user is enrolled in only one OTP method, then the choice step is skipped and the user is asked directly for the OTP value.
  • If the user has no OTP enrollments, then the "reject-on-missing-auth-method" comes into effect.
  • If the option "add_devices_to_choice" is enabled, the device options are added to the list. See the device auth method for details on what is added.
  • If the option "transients_in_choice" is enabled, the transient email and sms sources are listed as options.
  • If the option "voice_in_choice" is enabled,then voice OTP is listed as an option.
choice-then-otp The user is asked to choose of one of their OTP enrollments. After the choice is made, the OTP validation is initiated and the user is prompted for the OTP value.
Note:
  • If the user is enrolled in only one OTP method, then the choice step is skipped and the user is asked directly for the OTP value or device verification.
  • If the user has no OTP enrollments, then reject-on-missing-auth-method comes into effect.
  • If the option "add_devices_to_choice" is enabled, the device options are added to the list. See the device auth method for details on what is added.
  • If the option "transients_in_choice" is enabled, the transient email and sms sources are listed as options.
  • If the option "voice_in_choice" is enabled, then voice OTP is listed as an option.
password-then-device A Verify password must be provided, and if successfully provided, the user is asked to validate themselves by using the IBM Verify App on their phone.
device The user is asked to validate themselves by using the IBM Verify App on their phone. If multiple devices are available, the user is prompted for a choice.
Note: The option "add_devices_to_choice="determines whether to use fingerprint or userPresence. Only one of those two attributes can be used for a particular device.
password-then-transsmsotp A Verify password must be provided, and if successfully provided, the user is asked to provide the OTP sent by SMS to their mobile phone. The phone number is the one that is set in their user record.
transsmsotp The user is asked to provide the OTP sent by SMS to their mobile phone. The phone number is the one that is set in their user record.
password-then-transemailotp A Verify password must be provided, and if successfully provided, the user is asked to provide the OTP sent to them by email. The email address is the one that is set in their user record.
transemailotp The user is asked to provide the OTP sent to them by email. The email address is the one that is set in their user record.
voiceotp A call is made to the user's phone and a voice message informs the user of the OTP value that must be used to validate the login.
If "password" is not a part of the auth-method value, for example, "device", then the libpam_ibm_auth.so module can be prefixed by the standard UNIX/Linux PAM module to authenticate a local password to form the two factors. It can also be left out for a password-less authentication.
accept_on_missing_auth_method
This argument is optional. If set, and the user is not registered for second factor authentication, the user is authenticated. If this option is not set and the user is not registered for second factor authentication, the user is not authenticated.
otp_prompt={promt_str}
This argument is optional and defaults to the English string "Enter OTP %C- ". This string is displayed when the user is requested for OTP input. Any %C in the prompt is replaced by the OTP correlation, or the empty string for TOTP. Any %% in the prompt is replaced by a single %.
password_first
This argument is optional. It affects only the "password-and-totp" auth-method and determines the order of the password and TOTP values in the string that user must provide. Normally the password is provided at the end of the string after the separator character totp:password. If the argument is set, the password must be supplied at the start of the string before the separator character password:totp.
password_separator={sep_char}
This argument is optional and defaults to a password separator of : (colon). It affects only the "password-and-totp" auth-method and specifies the character that the user must use to separate the TOTP and password values.
ibm_auth_config={config_file_path}
This argument is optional and defaults to /etc/pam_ibm_auth.json. This configuration file defines the connection details to the Verify server under the ibm-auth-api section.
verify_method_order={order}
This argument is optional and defaults to "fingerprint,userPresence". This option chooses which of the two has priority. The default order prioritizes fingerprint if it is present.
Note: If the "add_devices_to_choice" is enabled, the "device" auth_method option uses only one of the methods, either fingerprint or userPresence.
verify_message={message}
This argument is optional and defaults to "Do you approve the request from {hostname}?" where {hostname} is replaced by the host name that the PAM module is running on. When the "device" auth_method is used, the user's device displays this message when the user is prompted to verify the access.
append={string}
This argument is optional and defaults to "". At the end of the process to map the UNIX user name to a Verify user name, this string is appended to the resulting Verify user name. A typical use case is to add the Verify user domain to the user, for example "@www.ibm.com" for the w3id user domain.
add_devices_to_choice
This argument is optional and defaults to not adding the user's device registrations to the "choice-then-otp" and "password-then-choice-then-otp" auth methods. If this argument is set, the device registrations are added to the user's list of choices for 2FA.
exempt_group={unix_group_name}
This value is optional and defaults to no exempt_group. When this argument is set, the specified UNIX group is used to determine whether a UNIX user login is exempt from 2FA authentication. If a UNIX user is in the group, it is exempt and is never asked for 2FA.
retry={num_retries}
This argument is optional and defaults to 3. It defines the number of retries a user has if they provide an invalid 2FA value, for example, a bad TOTP value. It also defines the number of retries for choosing which OTP type to use during the choice step.
failmode_insecure
This value is optional an defaults to a secure failmode. This argument affects the behavior when the Verify PAM module is unable to connect to the Verify server. If this argument is set, the 2FA authentication succeeds when the Verify server is unreachable. If the option is not provided set, all authentications that require a 2FA fail if the Verify server is unreachable.
gecos_field={field_number}
This argument is optional and defaults to not using the user's GECOS field. When set to a value in the range 1 - 32, the GECOS field that is specified from the UNIX user is used as the Verify user name. The append option still affects this value. The first GECOS field is defined as field number 1.
gecos_separator={char}
This argument is optional and defaults to , (comma). This value defines the GECOS field separator character.
id={pam_module_id}
This argument is optional and defaults to "pam_ibm_auth". If more than one occurrence of the Verify PAM module occurs in the set of PAM modules that are configured to authenticate a user, then each instance must be given a unique ID. Otherwise, the modules might interfere with each other.
identity_source={id}
This argument is optional and defaults to using the Cloud Directory identity source. If this argument is set, it specifies the identity source to be used to authenticate users. Users are authenticated against a configured LDAP Pass-Through identity source. A collection of configured identity sources and their IDs can be retrieved from a GET request to: https://<tenant>/verify/v1.0/authnmethods/password.
ignore_isvalidated
This value is optional and defaults to false. When set to true, the PAM module attempts to use relevant 2FA methods even if they are not validated.
transients_in_choice
This argument adds transient emails and phone numbers to the list of methods that are used to authenticate with OTP.
voice_in_choice
This argument adds voice OTP to the list of methods that are used to authenticate with OTP.
transient_choices={choices}
This argument lists the transient methods and choices that are made available. The value of the argument must be one or more "emails" and "phoneNumbers". Each choice must be separated by just a , (comma).
poll_timeout={seconds}
This argument specifies the time to wait for the user to validate the login from their device. If the time is exceeded, a timeout and failure to login occurs.
no_enrollments_in_choice

This argument specifies not to add SMS, email, or TOTP enrollments in the choices. To make a choice available, transients_in_choice or add_devices_to_choice or both must be configured.