IBM Verify Gateway for PAM IBM Contents IBM Verify Gateway for PAM on Linux 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/UNIX 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 operating system uses systemd 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. c) 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