Installing TraitWare PAM Module for SSH and SFTP

Posted on May 1, 2019

Overview

  • With TraitWare PAM and the TraitWare QR or PreAuth™ methods, you will be able to protect the following endpoints:  login, GDM, KDM, XDM, SSH, SCP, SFTP, FTP, email clients, and any PAM aware services from root access.  
  • TraitWare PreAuth™ requires the users to open and authenticate their TraitWare App prior to submitting a password.
  • Make sure you have administrative access to a TraitWare account
  • Make sure all users are added to the TraitWare Console and their access to your PAM application is enabled

Setup TraitWare OAuth Application

  • Navigate to admin.traitware.com and select Login with TraitWare
  • If you do not already have a TraitWare account, please sign up for a Trial
  • Scan the QR with your TraitWare app to sign in to the TraitWare Control console
  • If you are unable to sign in or do not already have a TraitWare Account setup, sign up for our free trial or contact us at support@traitware.com
  • Depending on your access level, you may need to drop down to the Customer level (Your console level will be listed on the left. You need to be at the TCC level. Select Console Level will let you change levels)
  • Your customer name will be in the top right once you are at the TCC.
  • Select Applications in the menu on the left
  • Select Add Application
  • Choose OAuth
  • Create a name for your application that is easily recognizable (i.e. SSH PAM)
  • For the Redirect and Return URIs, put n/a
  • Select Save Application
  • A new window will pop up with your Client Id and Client Secret
  • Make sure you save these in a safe place. They are needed for the above PAM setup
  • Select Ok
  • You will now see your application listed under your applications list.
  • You can always add more applications or modify existing ones.
  • If you select the application you just created, you will also find the ability to find your ClientId or to Regenerate your Client Secret.
  • You will also now be able to Enable Geo-Fencing. This will limit the use of the application to specific locations.
  • To update user access, navigate to Users on the left
  • Select Create User to add a new user
  • Select an existing user to Toggle their access to PAM
  • Note that multiple servers can be set up with the same users using the same application.
  • User access to servers can still be controlled.
  • Only users with registered usernames and passwords on a server will have access unless they guess or get someone else’s username and password.
  • Separate apps can be used to limit access and potential sharing or internal theft of passwords.

SSH Terminals

For secured SSH access, TraitWare PAM has been tested on the following terminals:

  • Gnome-terminal
  • Xterm
  • MAC Terminal
  • Windows Powershell (excludes ISE)
  • Windows Terminal (recommended to use cmd /u)
  • PuTTY (0.71 and up)
  • Cygwin Terminal

Setting Up Your Linux Machine

  • Make sure that your machine has at least 4 GB of RAM
  • For Redhat (RHEL), use at least version 7.1
  • Obtain a copy of the TraitWare PAM repository by contacting us at support@traitware.com

Debian

  • Copy the TraitWare PAM repo and its contents to your Linux machine
  • Enter the following commands in a terminal to install the file and its dependencies:
sudo apt install libjson-c2
sudo apt install libqrencode-dev
cd pam_traitware
sudo build
sudo install-deb
sudo service sshd restart

Redhat/Fedora

  • Copy the TraitWare PAM repo and its contents to your Linux machine
  • Enter the following commands in a terminal to install the file and its dependencies and configure it with SELinux:
sudo yum install json-c-devel.x86_64
sudo yum install qrencode-devel.x86_64
cd pam_traitware
sudo build
sudo install-rh
sudo chcon --reference /usr/lib64/security/pam_unix.so /usr/lib64/security/pam_traitware.so
sudo setsebool -P nis_enabled on
sudo service sshd restart

Finish Setting Up TraitWare Configuration

  • Your sshd configuration file will need to be updated with your unique TraitWare Client Id and Client Secret
  • If you have not already obtained these values, please complete the console OAuth application setup
  • Check to make sure you are using the correct clientId and clientSecret or you risk being permanently locked out of the server (if you need to reset the client secret for any reason, make sure you are already signed in to your root account to prevent lockout)
  • Next, add the module to the sshd config file. Enter this line at the top of /etc/pam.d/sshd:
auth required pam_traitware.so client_id=<yourclientid> client_secret=<yourclientsecret>
  • A properly configured Auth line will look like the following:
auth required pam_traitware.so client_id=88613211 client_secret=7Rd8}694abtyh7*2$@234sialghwiw93$owslhzpwiq39'9

Securely Log in with TraitWare

  • To remotely access your server running the TraitWare PAM over SSH or SFTP, enter the usual command: ssh username@host
  • Depending on your Linux configuration, you may receive a warning about the authenticity of the server. If you trust it, type yes to add the IP to the list of known hosts
  • A TraitWare QR will appear with two login options.

NOTE: The QR is rendered as UTF-8 characters which aren’t supported by all SSH clients. If you are using PuTTy, you will need to be running version .71 or above. If you are on Mac, the QR is less likely to scan on terminals with lighter backgrounds.

  • To Securely sign in using the QR, open the TraitWare app, choose your account, complete your authentication, and select Scan QR Code
  • Please note that your Authentication session will expire after 1 minute. You will need to break the call and run ssh again if it expires
  • At this point, you can either Scan and then enter 1 into the terminal, or enter 1 into the terminal and then Scan

If you receive an error, make sure you have registered your user with TraitWare in the TraitWare Console Setup

  • If you wish to use the Push notification (TraitWare PreAuth) method, open your TraitWare App, select the desired account, authenticate, and then leave your app open
  • Enter 2 into the terminal
  • Enter your TraitWare email (the email you registered TraitWare with for SSH PAM)

You will then have a push notification sent to your phone. Authenticate with your app and press “Approve”. You will have one minute to do this before the session expires.

Once you select APPROVE, you will be logged in to the host machine.

Debugging/Troubleshooting:

  • For security purposes, the user will receive a generic failed authentication prompt. All failed attempts are logged in detail to /var/log/secure for RedHat, or /var/log/auth.log for Debian.
  • If you want to turn off the TraitWare authentication for ssh into the server, comment out the above line using #
    This will disable the TraitWare PAM module (for ssh into the server).  Warning – this will leave your server less secure.