IBM Verify Gateway for PAM

IBM Contents

IBM Verify Gateway for PAM on and AIX systems...... 1 Overview...... 1 Installing the IBM Verify Gateway for PAM...... 2 SSH examples that use IBM Cloud Identity Verify for 2FA...... 3 Configuration...... 4 The PAM system configuration file...... 4 The module configuration file...... 10 ibm_authd...... 12 Uninstalling the IBM Verify Gateway for PAM...... 12 Troubleshooting...... 13

ii IBM Verify Gateway for PAM on Linux and AIX systems

Overview This document provides an overview of the AIX® and Linux/ PAM modules that were developed to provide Multi-Factor Authentication (MFA) via Cloud Identity Verify (CIV). This document describes the functionality that is provided in these versions of the PAM module. • IBM® Verify Gateway for PAM (on AIX), version 1.0 • IBM Verify Gateway for PAM (on Linux), version 1.0.1 The IBM Verify Gateway for PAM modules are composed of two components, pam_ibm_auth and ibm_authd. ibm_authd is a separate daemon process that can be started to maintain persistent TLS/TCP connections to the CIV server along with a shared authentication token and shared cookies. It is a custom form of “proxy” to CIV. Note: • Processes that invoke the pam_ibm_auth module must have an effective user ID of root. • Even though there is higher performance, using the ibm_authd method is optional and if it is not configured to use it the PAM module directly connects to the CIV service to operate.

Supported operating systems • Red Hat Enterprise Linux 7.6 x86-64 • Red Hat Enterprise Linux 7.0 x86-64 • Red Hat Enterprise Linux 6.9 x86-64 • Fedora 27 x86-64 • Fedora 28 x86-64 • Debian 9.7 x86-64 • Debian 8.11 x86-64 • openSUSE Leap 15 x86-64 • openSUSE Leap 42.3 x86-64 • SUSE Linux Enterprise Server 15 x86-64 • Centos 7.6.1810 x86-64 • Centos 6.10 x86-64 • Ubuntu 18.04 x86-64 • Ubuntu 16.04 x86-64 • AIX 7.2

IBM Verify Gateway for PAM on Linux and AIX systems 1 Installing the IBM Verify Gateway for PAM The Verify Gateway for PAM is installed from RPM.

Before you begin If the uses for services, then a “ibm_authd_64” service is set up, but not configured to run because the /etc/pam_ibm_auth.json file must be configured before it can run. After the set up of pam_ibm_auth.json, use these commands.

systemctl enable ibm_authd_64

systemctl start ibm_authd_64

About this task Note: The version and release in the .rpm and .deb, and .bff file names change over time. This documentation describes the functionality that is available in version 1.0.1, release 0. You can verify your version number by running the appropriate command, either rpm -q or dpkg -s.

Procedure 1. To install by using the .rpm files, do the following steps. a) Install the IBM Auth API for CIV. Issue the following command.

rpm -i ibm-auth-api-1.0.1-0.x86_64.rpm

b) Install the IBM PAM module for CIV. Issue the following command.

rpm -i pam-ibm-auth-1.0.1-0.x86_64.rpm

Note: Use the rpm -U command to upgrade to newer versions of the packages. 2. To install by using the .deb files, do the following steps. a) Install the IBM Auth API for CIV. Issue the following command.

dpkg -i ibm-auth-api-1.0.1-0.x86_64.deb

b) Install the IBM PAM module for CIV. Issue the following command.

dpkg -i pam-ibm-auth-1.0.1-0.x86_64.deb

Note: Use the dpkg -i command to upgrade to newer versions of the packages. 3. To install on IBM AIX, do the following steps. a) Ensure that OpenSSL is installed. b) Run smitty installp. ) Tell smitty to use the directory that contains the pam_ibm_auth.rte.1.0.0.0.bff file. d) Select the pam_ibm_auth fileset and install it. e) Edit /etc/pam_ibm_auth.json file and enter the CIV server connection details.

2 IBM Verify Gateway for PAM SSH examples that use IBM Cloud Identity Verify for 2FA As an example, take SSH authentication on RHEL 7 and add IBM CIV 2FA through a choice of all 2FAs that are available to the CIV user. This authentication is in addition to the local UNIX password login. Choose the CIV user name that you want to use for 2FA login, such as [email protected]. Subscribe the user to the required 2FA for testing. Note: The subscription process is outside the scope of this document. 1. The file /etc/pam.d/sshd controls the SSH authentication. It uses a common include file for the authentication, /etc/pam.d/password-auth. • To avoid disturbing all processes that use the common include file, make a copy of /etc/pam.d/ passsword-auth to /etc/pam.d/civ-password-auth so that it can be modified safely. • Edit /etc/pam.d/sshd to include the copied file, civ-password-auth, instead of password- auth. • Edit civ-password-auth and change the following line. Change

auth sufficient pam_unix.so nullok try_first_pass

to

auth requisite pam_unix.so nullok try_first_pass auth sufficient pam_ibm_auth.so auth_method=choice-then-otp gecos=field1

2. Ensure that /etc/pam_ibm_auth.json is set up correctly to communicate to the CIV server. 3. Manually start the ibm_authd daemon server. Issue the following command.

/opt/ibm/ibm_auth/ibm_authd_64 --conf_file /etc/pam_ibm_auth.json

4. Edit /etc/ssh/sshd_config. Ensure that “UsePAM yes” is set and set “ChallengeResponseAuthentication yes” to allow the user 2FA interaction with the CIV PAM module. 5. Select a UNIX user to test SSH and edit their GECOS value to your CIV username. See usermod or chin. 6. Restart sshd to ensure that it uses the updated configuration options. 7. SSH to the test user to see the 2FA take effect.

w3id As an example, take SSH authentication on RHEL 7 and add IBM w3id 2FA through a choice of all 2FAs that are available to the W3 user. This authentication is in addition to the local UNIX password login. Your CIV tenant must have w3id registry support available. Choose the w3id that you want to use for 2FA login, such as [email protected]. Subscribe the user to the required 2FA for testing. Note: The subscription process is outside the scope of this document. Set up the RHEL 7 system. 1. The file /etc/pam.d/sshd controls the SSH authentication. It uses a common include file for the authentication, /etc/pam.d/password-auth. • To avoid disturbing all processes that use the common include file, make a copy of /etc/pam.d/ passsword-auth to /etc/pam.d/civ-password-auth so that it can be modified safely. • Edit /etc/pam.d/sshd to include the copied file, civ-password-auth, instead of password- auth. • Edit civ-password-auth and change the following line. Change

auth sufficient pam_unix.so nullok try_first_pass

IBM Verify Gateway for PAM on Linux and AIX systems 3 to

auth requisite pam_unix.so nullok try_first_pass auth sufficient pam_ibm_auth.so auth_method=choice-then-otp w3id

2. Ensure that /etc/pam_ibm_auth.json is set up correctly to communicate to the CIV server. 3. Manually start the ibm_authd daemon server. Issue the following command.

/opt/ibm/ibm_auth/ibm_authd_64 --conf_file=/etc/pam_ibm_auth.json

4. Edit /etc/ssh/sshd_config. Ensure that “UsePAM yes” is set and set “ChallengeResponseAuthentication yes” to allow the user 2FA interaction with the CIV PAM module. 5. Select a UNIX user to test SSH and edit their GECOS value to ensure that it is in the w3id standard format. See usermod or chin. That standard format contains the w3id in its sixth field. For example,

[email protected]: XXX/X/XXXXXX//XXXX.XXXX/[email protected]

6. Restart sshd to ensure that it uses the updated configuration options. 7. SSH to the test user to see the 2FA take effect.

Configuration IBM Verify Gateway for PAM configuration consists of the system configuration file, the module configuration file, and the ibm_authd daemon.

The PAM system configuration file 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.

4 IBM Verify Gateway for PAM 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. try_first_pass This argument is a standard PAM UNIX module option. It is used only for an auth_method that validates a password, and is not for OTP validation. The try_first_pass option enables an authentication attempt by using the password that was supplied to previous modules in the chain. If the attempt fails or if no previous modules exist, a password prompt is displayed. use_first_pass This argument is a standard PAM module option. It is used only for an auth_method that validates a password, and is not for OTP validation. The use_first_pass option enables an authentication attempt by using the password that was supplied only to previous modules. Use of this option enables a password prompt only if the authentication module is the called first. 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 CIV server connection details. See “The module configuration file” on page 10. 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 CIV 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 CIV auth methods that involve a password. If that previously supplied password and the CIV password do not match, the authentication fails. This issue is a known limitation. Note: These password auth_methods might not be currently available with W3IDs.

Table 1: Acceptable values Value Description password Requires a valid CIV password.

IBM Verify Gateway for PAM on Linux and AIX systems 5 Table 1: Acceptable values (continued) Value Description password-and-totp A CIV 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 CIV 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 CIV 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 CIV 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 CIV 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.

6 IBM Verify Gateway for PAM Table 1: Acceptable values (continued) Value Description 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. password-then-device A CIV 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 CIV 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 CIV 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.

IBM Verify Gateway for PAM on Linux and AIX systems 7 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 CIV 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 CIV user name, this string is appended to the resulting CIV user name. A typical use case is to add the CIV 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.

8 IBM Verify Gateway for PAM failmode_insecure This value is optional an defaults to a secure failmode. This argument affects the behavior when the CIV PAM module is unable to connect to the CIV server. If this argument is set, the 2FA authentication succeeds when the CIV server is unreachable. If the option is not provided set, all authentications that require a 2FA fail if the CIV 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 CIV 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. w3id This argument is optional and is only a convenience feature. When this argument is set, it enables a number of settings with set values: gecos_separator=/ gecos_filed=6 [email protected] add_devices_eo_choice id={pam_module_id} This argument is optional and defaults to "pam_ibm_auth". If more than one occurrence of the CIV 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:///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. 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.

IBM Verify Gateway for PAM on Linux and AIX systems 9 The module configuration file The module configuration file is a JSON formatted file that is used to define the connection to the CIV server. By default it is called /etc/pam_ibm_auth.json.

Format

{ "ibm-authd": { "trace-file": "/tmp/ibm-authd.log", }, "pam": { "trace-file": "/tmp/pam-ibm-auth.log", }, "ibm-auth-api": { "client-id": "xxxxxxxx", "client-secret": "xxxxxxxx", "protocol": "https", "host": "xxxxx.ice.ibmcloud.com", "port": 443, "max-handles": 16, "authd-port": 12 } }

"ibm-auth-api":{} This section configures the connection to the Cloud Identity Verify server.

Format

“ibm-auth-api”:{ “client-id”:”xxx”, “client-secret”:”xxx”,

… }

Values: "client-id":"84e8da25-d7ed-47cc-9782-b852cb64365c" This value is required. An IBM Cloud Identity API client must be created for use by the IBM Verify Gateway for PAM module. “client-secret”:"*********" This value is required. The IBM Cloud Identity API client is given a password when it is created and must be set in this configuration setting. Note: This client-secret can be set in an obfuscated form. Use the /opt/ibm/ibm_auth/ ibm_authd --obf command to generate the obfuscated version and use the alternate setting:

“obf-client-secret”:”KsjKZsKrbbgNaPe7+kYIcOyWzZdzYNtF4KlCyYoNEFA=”,

"protocol":"https" This value is optional and defaults to “https”. This protocol is used to communicate to the IBM Cloud Identity server. Either value, “http” or “https”, can be used. When https is used and the /etc/ pam_ibm_auth.pem file is present, the IBM Cloud Identity server certificate and server name are validated. "host":"slick.ice.ibmcloud.com" This value is required. It identifies the IBM Cloud Identity server that you are using. "port":443 This value is optional and defaults to 443. This port is the port that the IBM Cloud Identity server is listening on for requests.

10 IBM Verify Gateway for PAM "max-handles":16 This value is optional and defaults to 16. This value is the maximum number of parallel connections that the IBM Verify Gateway for RADIUS server makes to the IBM Cloud Identity server for user authentication. "authd-port": 12 This value is optional. This value is the port that the local CIV proxy listens on. If this argument is set, the local proxy mode of the API is enabled and the /opt/ibm/ibm_auth/ibm_authd daemon must be running on the same system on which the CIV PAM is running. "proxy": "http://proxy.ibm.com:1080" This value is optional and defaults to not using a proxy, and to use direct connections. Set the proxy to access the CIV tenant. The values is a host name or a dotted numerical IP address. A numerical IPv6 address must be written within [brackets]. To specify port number in this string, append :[port] to the end of the host name. The proxy's port defaults to port :1080. The proxy string can be prefixed with [scheme]:// to specify which kind of proxy is used. http:// HTTP Proxy. The default type when no scheme or proxy type is specified. https:// HTTPS Proxy. Added in 7.52.0 for OpenSSL, GnuTLS and NSS. socks4:// SOCKS4 Proxy. socks4a:// SOCKS4a Proxy. The proxy resolves the URL host name. socks5:// SOCKS5 Proxy. socks5h:// SOCKS5 Proxy. The proxy resolves the URL host name. Setting the proxy string to "", an empty string, explicitly disables the use of a proxy, even if an environment variable is set for it. A proxy host string can also include protocol scheme http:// and embedded user and a password. "proxytunnel":true This value is optional and defaults to true if the proxy is enabled. Set the proxytunnel argument to true to make CIV tenant operation tunnel through the HTTP proxy. Using a proxy is different than to tunneling through it. Tunneling means that an HTTP CONNECT request is sent to the proxy, asking it to connect to a remote host on a specific port number and then the traffic is passed through the proxy. Proxies white-list the specific port numbers that it allows CONNECT requests to. Typically, only ports 80 and 443 are allowed.

"ibm-authd":{} A trace file can be set for the ibm_authd process.

"pam":{} A trace file can be set for the pam_ibm_auth.so module.

Other files The file /etc/pam_ibm_auth.pem can be set up to allow verification of the tenant certificate and to verify that the tenant host name is valid for the certificate that it provides. This text file contains one or more PEM CA certificates, base64 translation of the x509 ASN.1 CA public keys.

IBM Verify Gateway for PAM on Linux and AIX systems 11 ibm_authd The ibm_authd daemon is the connection and bearer token caching proxy that the CIV PAM module uses to avoid creating HTTPS connections and authenticating to the CIV server every time it is invoked. Typically the location is /opt/ibm/ibm_auth/ibm_authd. The daemon is used by the CIV PAM module if the "ibm-auth-api" and "authd-port" values are set in the JSON configuration file. If that configuration value is not set, then the CIV PAM module goes directly to the CIV server. The daemon has the following options: --conf_file= This option is optional and specifies the JSON configuration file that contains the connection details to the CIV server. The value defaults to /etc/pam_ibm_auth.json. --pid_file= This option is optional and specifies the file into which the daemon writes its process ID. This value defaults to /var/run/ibm_authd.pid. --nodaemon This option stops the server from running in the background. --obf [ ...] This option is a non-server operation that allows the obfuscation of a password for placement in the JSON configuration file. For example,

# /opt/ibm/ibm_auth/ibm_authd --obf passw0rd

Ch61srtgUikk0iixvYyrk4hcA5eiGMim7iDn83Ol8WY=

The value output can be used to obfuscate the "ibm-auth-api" and "client-secret" values. Remove the current "client-secret" entry and replace it with the obfuscated value. For example,

"obf-client-secret": "Ch61srtgUikk0iixvYyrk4hcA5eiGMim7iDn83Ol8WY="

Uninstalling the IBM Verify Gateway for PAM You can use the RPM Package Manager to uninstall the IBM Verify Gateway for PAM.

Procedure 1. To uninstall the PAM module for CIV by using the .rpm files, do the following steps. a) Uninstall the IBM PAM module for CIV. Issue the following command.

rpm -e pam-ibm-auth-1.0.1-0.x86_64

b) Uninstall the IBM Auth API for CIV. Issue the following command.

rpm -e ibm-auth-api-1.0.1-0.x86_64

2. To uninstall the PAM module for CIV by using the .deb files, do the following steps. a) Uninstall the IBM PAM module for CIV. Issue the following command.

dpkg --remove pam-ibm-auth-1.0.1-0.x86_64

b) Uninstall the IBM Auth API for CIV.

12 IBM Verify Gateway for PAM Issue the following command.

dpkg --remove ibm-auth-api-1.0.1-0.x86_64

3. To uninstall the PAM module for CIV from AIX operating systems by using the installp command, do the following step. a) Uninstall the IBM PAM module for CIV. Issue the following command.

installp -u pam_ibm_auth.rte

Troubleshooting Use these methods to debug CIV PAM authentication issues. • Examine the syslog for errors. On RHEL 7, use the journal command. For example, if the auth_method option was spelled incorrectly, choice_then_otp instead of choice-then-otp, the error might be Aug 28 10:41:15 fedora26.home.com pam_ibm_auth[77017]: Error: auth_method=choice_then_otp: Not a valid auth method. • Enable syslog debugging from the pam_ibm_auth module by adding the option debug to the PAM configuration file. For example,

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

Then examine the DEBUG syslog output • Enable file base trace of all CIV REST operations in the ibm_authd. Edit the /etc/ pam_ibm_auth.json and add the trace file configuration:

"ibm-authd":{ "trace-file":"/tmp/ibm_authd.log" }

You can either Restart the ibm_authd daemon, kill it then start it again. Send a SIGHUP signal to it, kill -HUP and it reloads its configuration and continues running. Run the SSH test and examine the /tmp/ibm_authd.log file to observe the interaction with CIV.

Common issues • SELinux can prevent programs that use the PAM module from connecting to CIV or to ibm_authd. If you're facing connectivity issues, use the sealert tool to investigate whether SELinux is denying access. • Ensure that your network firewall is configured to allow outgoing HTTPS connectivity to your CIV tenant.

IBM Verify Gateway for PAM on Linux and AIX systems 13 IBM®