The PAM 2FA module provides a second factor authentication, which can be combined with the standard PAM-based password authentication to ask for:
- What you know: user account password ( standard PAM modules )
- What you have (pick one or more of): (PAM 2FA)
- A TOTP Application on your phone
- A Yubikey
You need the following packages installed in order to properly build, install and/or use this module:
- Redhat/CentOS/SLC6/CC7 (rpm): pam-devel, curl, curl-devel
- Debian/Ubuntu (pkg): libpam-dev, libcurl, libcurl-dev
In order to BUILD the pam module and to INSTALL you need to type the following commands:
autoreconf -i
./configure
make
sudo make install
Note: You may want to use option --with-pam-dir in order to get the pam module be installed in the proper directory.
In order to use this PAM-2FA module you need to configure your PAM setup by adding a line to an appropriate file in /etc/pam.d/
auth required pam_2fa.so [ PARAMETERS ]
In order to use PAM-2FA module with ssh connections, you need to do the following:
- Add the preceding line with your parameters in /etc/pam.d/sshd
- Add the following lines to your SSHD configuration (/etc/ssh/sshd_config):
ChallengeResponseAuthentication yes
UsePAM yes
- Restart the SSHD daemon
| Parameter | Optional ? | Description | Default |
|---|---|---|---|
| debug | Optional | Will show every STDOUT messages in the console | |
| capath | Optional | Specify the path where trusted certificates are | |
| gauth_uri_prefix | Mandatory for TOTP support | Prefix of URI of the REST API for TOTP | |
| gauth_uri_suffix | Mandatory for TOTP support | Suffix of URI of the REST API for TOTP | |
| yk_uri | Mandatory for Yubikey support | Specify the URI of the REST API for yubikey authentication | |
| domain | Mandatory for Kerberos support | Domain used for extracting the username from kerberos principals | |
| trusted_file | Optional | Specify the path (relative to user home) to a trusted user list. Used for system users. If 'domain' is not NULL, principals instead of users are expected | ".k5login" |
This PAM module delegate all the crendetial validation on remote REST APIs described here
TOTP are validated via a POST on ${gauth_uri_prefix}/${username}/${gauth_uri_suffix} with the otp passed in the post data.
It expects 200 return code for valid OTPs and any return code >= 400 for invalid ones.
Yubikeys are validated via a POST on ${yk_uri} with the following post data (in json):
{
"username": ${username},
"yubicode": ${otp}
}
It expects the raw string 'true' for valid OTPs and anything else for invalid ones
For a previous implementation of this module, using a LDAP and different endpoint, please refer to the v1.x branch