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.

IBM Cloud Identity Verify currently supports the following Operating Systems (as of 4/30/19):

• 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
  
  

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

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"
     }
   }​

• 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
• 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

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/bash​

      
      We 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

Cloud Identity Authentication as a Service (AaaS) Cookbook