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).
#%PAM-1.0
auth required pam_sepermit.so
auth substack password-auth
auth include postlogin
...
#
# Authentication
#
authexec auth required pam_aix
dtaction auth required pam_aix
dtsession auth required pam_aix
...
module_interface control_flag module_name [module_arguments]
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
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 thegecos_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.IfTable 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 usefingerprint
oruserPresence
. 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. password-and-totp-or-device If a TOTP value is detected in the user-provided password, then the equivalent to the password-and-totp
method is used. For more information, see password-and-totp.If a TOTP value is not detected in the user-provided password, then the equivalent to the
password-and-device
method is used. For more information, see password-then-device.Note: If the user's actual password begins or ends with six digits and a separator, it can be mistaken as an embedded TOTP value by the RADIUS server. For example, thepassword-first
option is set to false and the password begins with the six digits and separator. Similarly, if set to true, and the password ends with a separator and six digits, the same condition occurs. In either situation, a device push cannot be used as a second factor for the RADIUS authentication. The RADIUS server interprets it as a TOTP value and tries to validate it. The validation fails and the authentication is rejected."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 charactertotp:password
. If the argument is set, the password must be supplied at the start of the string before the separator characterpassword: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, eitherfingerprint
oruserPresence
. - 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. - 2fa_group={unix_group_name}
- This value is optional. When this option is set, the specified UNIX group is used to determine whether a UNIX user login requires a 2FA. When this option is set and the UNIX user is not in the group, the user is not prompted 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 totrue
, 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
oradd_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:
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.
2FA Type | Default | Enablement/Disablement Option | Description |
---|---|---|---|
totp smsotp emailotp | enabled | no_enrollments_in_choice | Time, SMS, and Email based one-time-password are included by default and must be explicitly disabled for them to not be present. |
device | disabled | add_devices_to_choice | Device push, both biometrics (fingerprint) and presence (access to device app), are disabled as choices by default and must be explicitly enabled if required. The option verify_method_order determines the priority and which are used. |
transsmsotp transemailotp | disabled | transients_in_choice | Transient (unverified user account values for mobile phone and email) are disabled as a choice by default and must be explicitly enabled if required. The option transient_choices= determines which of smsotp and/or emailotp are used. |
voiceotp | disabled | voice_in_choice | Voice call-back based one-time-password is disabled by default and must be explicitly enabled if required. The user must explicitly enroll in this method for it to be available. |