In this article we are going to look at configuring two factor + authentication via PAM using OATH. This is a simple and private way + to increase the security of your systems. Even if you are not familiar + with the term, it is likely that you + have used OATH before. OATH (specifically TOTP) is the rotating 6 + digit code that you get from scanning a QR code when setting up 2FA + on an account.

+ +

This example will show how to configure 2FA for SSH logins to a + server, but can easily be generalized to cover other programs or + even all authentication on a system. The two factors here will be + public key authentication and then the OATH/TOTP code. + It is highly recommended that you remain SSHd into your server + until after testing to avoid locking yourself out in the event + of a configuration error.

+ +

Install Packages

You only need to install a single package on the server side.

+ +

apt install libpam-oath

+ +

On the client machine that will be SSHing to the server install + these two packages.

+ +

apt install oathtool qrencode

+ +

Configure OATH

Create the OATH configuration file /etc/users.oath. + This file will contain the OATH secret keys so permissions need to be + set to only allow the root user to view it.

+ +

touch /etc/users.oath
+chown root: /etc/users.oath
+chmod 600 /etc/users.oath

+ +

Generate a secret key for the TOTP. Treat this secret key as you + would your SSH or GPG private key. Anyone who has this key will be able + to generate the code needed to authenticate.

+ +

openssl rand -hex 10

+ +

Now we define the TOTP configuration for our user. If you were + setting this up for multiple users you would make one entry per line. + Open /etc/users.oath and add this line. + user is the username of the account you will SSH into. + Replace the long string of numbers and letters with the secret key + you just generated.

+ +

HOTP/T30/6 user - 00112233445566aabbcc

+ + +

Configure PAM

Now we need to tell PAM to use OATH to authenticate sshd. Do that + by opening /etc/pam.d/sshd and adding the following + line to the top of the file.

+ +

auth sufficient pam_oath.so usersfile=/etc/users.oath window=30 digits=6

+ +

This tells PAM to consider a valid 6 digit code as fully authenticated + and to skip any other processing that may normally occur, such as + requesting a password.

+ +

Configure SSHD

We need to make a few changes to the sshd configuration to allow + OATH to work properly. Open the sshd configuration file at + /etc/ssh/sshd_config and make the following changes.

+ +

AuthenticationMethods publickey,keyboard-interactive
+PubkeyAuthentication yes
+PasswordAuthentication no
+ChallengeResponseAuthentication yes
+UsePAM yes

+ +

The AuthenticationMethods line specifically tells + sshd that a user needs to both have an authorized SSH key and know + the proper 6 digit code to login.

+ +

Restart sshd to apply the changes

+ +

systemctl restart sshd

+ +

Test the Changes

From your client ssh into your server as normal. Instead of + connecting as you have been, you should now see a prompt for your + one time password. You can use oathtool to get + the code. Again, replace the long string of numbers and letters + with the secret key you generated on the server.

+ +

oathtool --totp -d6 00112233445566aabbcc

+ +

Enter that 6 digit code into the prompt and you will be logged + into your server.

+ +

Now, in the unlikely event that your SSH private key is stolen, + an attacker still won't be able to access your server!

+ +

Managing your TOTP

You probably don't want to run the oathtool command everytime you + need your code, and while you could make an alias, that would require + storing your secret key in plaintext. Here are some better options.

+ +

pass otp is an extension to the command-line + password manager pass for handling TOTP. + Use this if you are already using pass
KeePassXC is a graphical password + manager that can manage TOTP
Gnome Authenticator is a graphical + TOTP manager for the GNOME desktop environment

+ +

You may also want to generate a QR code for easy setup on another + device. Rerun the same oathtool command as before with the -v flag + to get the base32 version of your secret key.

+ +

oathtool --totp -v -d6 00112233445566aabbcc
+--------------------------------
+Hex secret: 00112233445566aabbcc
+Base32 secret: AAISEM2EKVTKVO6M
+Digits: 6
+Window size: 0
+TOTP mode: SHA1
+Step size (seconds): 30
+

+ +

Then use qrencode to generate the QR code image.

+ +

qrencode -o totp.png 'otpauth://totp/user@server?secret=AAISEM2EKVTKVO6M'

+ +