The PAM system configuration file

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

auth sufficient pam_ibm_auth.so auth_method=choice-then-otp 

[otp-prompt=Enter OTP %C- ]

user_env={name}

Add a PAM environment variable containing "{name}={user-json}" for downstream PAM modules. The value of {user-json} is a string containing the IBM Security Verify user information in JSON format. Primarily used to assist PAM Module developers integrate with the IBM PAM module.

prompt_choice_start={prompt}

The {prompt} string is output immediately before the list of 2FA choices. For example, if {prompt} contained "Choose one of:\n" you might see:

Choose one of:
1) user@us.ibm.com
2) 15551234567
3) TOTP
Your choice (1->3):

prompt_choice_end={prompt}

The {prompt} string is output immediately before the list of 2FA choices. Any %T value within this {prompt} is replaced with a number representing the total number of choices. For example, if {prompt} contained "Your choice (1->%T):" you might see:

Choose one of:
1) user@us.ibm.com
2) 15551234567
3) TOTP
Your choice (1->3):

prompt_trans_email={prompt}

prompt_trans_sms={prompt}

prompt_totp={prompt}

prompt_email={prompt}

prompt_sms={prompt}

prompt_voice={prompt}

prompt_device_presence={prompt}

prompt_device_biomertic={prompt}

These arguments customize the prompt option for each 2FA type. The following substitutions can be applied:

• %I The 2FA option index
• %N The value that is associated with the 2FA option name (for example, an email address)
• %T The total number of choices

For example, if prompt_trans_sms="%I) Unvalidated SMS %N\n" you might see:

Choose one of:
1) user@us.ibm.com
2) Unvalidated SMS 15551234567
3) TOTP
Your choice (1->3):

Note: These options can cause the PAM module arguments to become very long and difficult to manage. To overcome this many of the module arguments can be moved into the /etc/pam_ibm_auth.json file, see the "additional-args" feature under the "pam" object in this file.

device_prompt={prompt}

If set, then the message specified is displayed for the user when they need to approve on a 2FA device. The use of this with SSH. has some limitations. Some SSH servers pass on a message (without also prompting for input), some do not. By default, no prompt is sent, it relies on the user's device for the alert.

user_name_attr={attr_name}

Maps the user name that is provided to PAM to an IBM Security Verify user, based on matching an attribute that is contained on the IBM Security Verify user. For example, the PAM user name could be added to an IBM Security Verify user custom attribute called other Username. That custom attribute specifies

user_name_attr=urn:ietf:params:scim:schemas:extension:ibm:2.0:User:customAttributes.otherUserName

By default, the user attribute "userName" is used to locate the IBM Security Verify user that matches the PAM user name.

gecos_match={regex}

gecos_replace={replace_format}

These arguments are used as an alternative to the gecos_field/gecos_separator method. The {regex} is used to match the user's GECOS value and extracts the value for providing to the gecos_replace format. See the regex(7) man page for details on regex.

The {replace_format} value is used to generate the IBM Security Verify user's name. In the {replace_format} any $N, where N is 1 -> 9, is replaced by the corresponding regex atom, (pat), from the {regex} match.

For example,

[gecos_match=^([^/\]+)/([^/\]+)/([^/\]+)] [gecos_replace=$3/$1@MyRealm]

Note: when using the PAM [arg] method, any embedded ] chars in arg need to be quoted by using \.

If the GECOS field was "Test User/+15551234567/ibm.com" then the user that is generated is "ibm.com/Test User@MyRealm"

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.
password-then-voiceotp	An IBM Security Verify Password must be provided. If it is successfully provided, a call is made to the user's phone, and a voice message informs the user of the OTP value that muse 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.

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.

id_link_attr={attr_name}

When there are multiple identity sources defined in the tenant and they are using identity linking, this configuration item defines the name of an attribute from the user located by "user_name_attr" that identifies the username to validate the password against. Example {attr_name} values:

• "urn:ietf:params:scim:schemas:extension:ibm:2.0:user:linkedAccounts.myOnPremIdSource"
• "emails.type%20eq%20%22work%22%20and%20emails.value"
• "urn:ietf:params:scim:schemas:extension:ibm:2.0:user:customAttributes.myCustomAttribute"
• "userName"

Defining the 2FA methods provided in the choice auth_methods

How to enable or disable the Second Factor Authentication types presented in the choice auth_methods.