ORIGINAL PUBLISH DATE: December 27, 2018


Protection for Unix based terminal sessions to secure shell (SSH) and other services can be quickly performed by introducing the IBM Verify Gateway for PAM. This authentication module runs locally on the Unix system and makes an outbound call to the Cloud Identity Verify APIs to obtain two-factor authentication methods to verify the user. Since PAM is customizable, you can easily add multi-factor to other services to step up authentication whenever necessary. This blog is designed to walk you through the basic setup for a CentOS system that uses a local system user.

Before You Begin

1. Find a CentOS, RHEL, or Fedora machine for use in this walk-through (virtual machines will work fine)
2. Download the latest IBM Verify Gateway for PAM RPMs onto the Linux system from the link below:
   1. XForce Exchange Download
   2. Unzip the files into a new folder called ~/ibm
3. Create an API Client ID and Secret from your Cloud Identity portal using the method located in this blog under the “Getting Credentials” section. You will need the following permissions:
   1. Authenticate any user
   2. Manage second-factor authentication enrollment for all users
   3. Manage users and groups
   4. Read second-factor authentication enrollment for all users
   5. Read second-factor authentication method configuration
   6. Read users and groups
4. Identify the username of the user and create matching user in CIC.
   1. To get the user information on your Linux system, run the getent passwd command.
   2. By default, the IBM Verify PAM module will use the username of the user, however additional configurations can be added to use the gecos field number as well as parse the gecos field with specific separators.
      Note: For this blog, we will be using local users in both the terminal and Cloud Identity for simplicity. More advanced scenarios would use a central directory for users in both Cloud Identity and Linux.

Installation

Install the RPMs by running the following commands with sudo or as root. Depending on the version you download, the file names may differ.

1. Install the Authentication API module
   [root@localhost ibm]# rpm -i ibm-auth-api-1.0-0.x86_64.rpm
2. Install the PAM Daemon
   [root@localhost ibm]# rpm -i pam-ibm-auth-1.0-0.x86_64.rpm
3. Configure the JSON file
   A JSON file has now been created for you, but you will need to edit this file. Because this file contains sensitive API key information, is is good to check the permissions of the file after the configuration has been completed. The JSON file is located at /etc/pam_ibm_auth.json. The contents of the file contain the client-id, client-secret, and the Cloud Identity tenant name (host). The Client ID and Client Secret are the keys you obtained from the API configuration in the Cloud Identity portal. The host name for your tenant is the subdomain of your tenant’s URL (e.g. sample.ice.ibmcloud.com -> sample)These are the only three things variables you are required to change first. However, it is a good idea to uncomment the trace logs for additional debugging. Any changes to this file after the daemon has started will require a restart of the service.

   {
   “ibm-auth-api”:{
   “client-id”:”********-****-****-****-************”,
   “client-secret”:”**********”,
   “protocol”:”https”,
   “host”:”****.ice.ibmcloud.com”,
   “port”:”443″,
   “authd-port”:12,
   “max-handles”:”16″
   },
   “ibm-authd”:{
   /* “trace-file”:”/tmp/ibm_authd.log” */
   },
   “pam”:{
   /* “trace-file”:”/tmp/pam_ibm_auth.log” */
   }
   }
4. Enable and Start the Auth Daemon
   If the OS uses systemd for services, then a “ibm_authd_64” service is set up, but not configured to run as the /etc/pam_ibm_auth.json file. It must be configured before it is able to run. After the setup of the pam_ibm_auth.json file, use the commands:
   

   [root@localhost ibm]# systemctl enable ibm_authd_64
   [root@localhost ibm]# systemctl start ibm_authd_64​

5. Be Aware of SELinux
   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. I have disabled SELinux for this blog, but for production systems, it is good to apply security whitelists to the CIV domains as well as the ibm_authd service.

Setup PAM for SSH Multi-Factor

 

To use IBM Verify with SSH, you must edit the PAM configuration for sshd.

1. Copy the Password Auth File
   The file /etc/pam.d/sshd controls the SSH authentication. However, it uses a common include file for the
   authentication, /etc/pam.d/password-auth. Run the following command:
   [root@localhost ~]# cp /etc/pam.d/password-auth /etc/pam.d/civ-password-auth
2. Edit the new civ-password-auth File
   Using your favorite editor, make the following changes to the /etc/pam.d/civ-password-auth file. 
   Before:
   auth sufficient pam_unix.so nullok try_first_pass

   After:

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

   Note: In PAM, changing the pam_unix.so to be “requisite” means that in order for pam_ibm_auth.so to be invoked, this must first succeed.

   Note: If you see a message like “No second factor authentication enrolments are available.” when trying to authenticate then you can either include transients_in_choice and add_devices_to_choice or if you don’t care about enrollments of the user,  then use accept_on_missing_auth_method.

   A few configurations that may be helpful are:

   1. Use the user’s profile email address and phone number
      auth sufficient pam_ibm_auth.so auth_method=choice-then-otp transients_in_choice
   2. To use the gecos field and transient profile information:
      auth sufficient pam_ibm_auth.so auth_method=choice-then-otp transients_in_choice gecos_field=1

      Example user entry, red highlights the gecos field:
      jessica:*:1002:1002:jessica:/home/jessica:/bin/bash

   3. To use a specific attribute from the gecos field given a separator:
      Given a user entry such as jessica:*:1002:1002:jessica|bretton|jessica|jessica@cse-bank.com:/home/jessica:/bin/bashWe can use the following:
      auth sufficient pam_ibm_auth.so auth_method=choice-then-otp gecos_field=3 gecos_separator=|
   4. Append a domain to a username
      auth sufficient pam_ibm_auth.so auth_method=choice-then-otp append=@cse-bank.com

      Note: If using a 3rd Party Identity Provider, you should also append the realm to the username. For example, if the realm of the 3rd party Identity Provider such as ISAM or ADFS, you will want to ensure that your append attribute matches the following naming convention: append=@domain@realm (e.g. append=@cse-bank.com@realm)

   5. To use allow for IBM Verify push device registrations in choice
      auth sufficient pam_ibm_auth.so auth_method=choice-then-otp transients_in_choice add_devices_to_choice
   6. All additional configurable options can be found here.
3. Change SSH PAM to use IBM Verify
   In the file /etc/pam.d/sshd, in the auth stanza only, replace password-auth with civ-password-auth.
4. Test the Configuration
   Back in the terminal window, perform a localhost SSH connection using the following command:
   ssh testuser@localhost
   You should first be prompted for your local password to the system, then a call will be made to Cloud Identity to obtain the 2FA enrollments for the user.
   [root@localhost ~]# ssh testuser@localhost
   Password:
   1) 15125551012
   2) ibmtestuser@domain.com
   ? 2
   Enter OTP 9430-582132
   Last failed login: Thu Dec 27 14:35:13 CST 2018 from localhost on ssh:notty
   There was 1 failed login attempt since the last successful login.
   [testuser@localhost ~]$

Take It to the Next Level

Whether you want to layer in LDAP for two-factor or add conditional access to the PAM substacks, the IBM Verify PAM can be easily configured and applied to your Unix systems to protect them from remote access with 2FA and Push Verification with IBM Verify application. You can also expand this to perform 2FA on GUI based authentications as well depending on your configuration of Linux. Full documentation can be found here for the IBM Verify PAM service.

Cloud Identity Authentication as a Service (AaaS) Cookbook

For a full walk-through of using Cloud Identity Verify and Connect for AaaS, download the Cookbook here: Download Now