Enable Two-Step Authentication on Ubuntu/Debian with Google’s libPAM

With security being on the top of everyone’s mind these days. We come to a point where we have to consider extra security for our servers. Over the weekend I decided to add Google Authenticator’s PAM module to my web servers as an added layer of security.

What is Google Authenticator?

The Google Authenticator project includes implementations of one-time passcode generators for several mobile platforms, as well as a pluggable authentication module (PAM). One-time passcodes are generated using open standards developed by the Initiative for Open Authentication (OATH) (which is unrelated to OAuth).

These implementations support the HMAC-Based One-time Password (HOTP) algorithm specified in RFC 4226 and the Time-based One-time Password (TOTP) algorithm specified in RFC 6238.

First to start off, you will need to acquire the Google Authenticator app from the respective application market place or click here visit the google code site to get the install links. Install the app and get a feel for it, it is a very simple app to use.

Ubuntu/Debian

Login to your server via ssh or the console. For these instructions, it is important to keep the ssh session alive until you verify that the authentication is working correctly.

Prerequisites

Since we are installing a authentication method that will require time based tokens. It is important that your system’s time be correct. I highly recommend syncing your time with an internet NTP server. I suggest using the pool.ntp.org servers.

You will need to install the following packages if you don’t have them already.

sudo apt-get install gcc git-core libpam0g-dev make

Then we will download, compile and install the current code for the Google Authenticator project.

cd ~
git clone https://code.google.com/p/google-authenticator/
cd google-authenticator/
cd libpam
make install

This process may take a a minute or two. Once done you should see the following output, or simular output on the last lines.

cp pam_google_authenticator.so /lib/security
cp google-authenticator /usr/local/bin

Now we need to edit the config files that will add the google PAM module to the pam sshd config file located at /etc/pam.d/sshd. Some tutorials state that you should add it to /etc/pam.d/common-auth file. I disagree with this, as it does not take into account other software you have installed, and what authentication they are using. Specifically, when I added it to /etc/pam.d/common-auth on my server it broke imap for my mail server.

Open up the /etc/pam.d/sshd file and look for the below line:

@include common-auth

Below the above line add the following:

auth    required                        pam_google_authenticator.so

I placed it here because I prefer to be asked my password first, you can move it above the @include common-auth if you like, and it will ask for the token first.

Now we need to edit your /etc/ssh/sshd_config file to turn on ChallengeResponseAuthentication. Locate the line in the sshd_config file and set it to yes like below.

ChallengeResponseAuthentication yes

Restart the sshd service.

service ssh stop
service ssh start

We now need to set up the Google Authenticator.

google-authenticator

You will be asked a series questions.

Do you want authentication tokens to be time-based (y/n) Yes

Do you want authentication tokens to be time-based (y/n) y

Once you enter yes to the first it will output some important information. Copy this information to a text file for later. (In this output you will see “Your emergency scratch codes are:” Copy those codes and keep them in a secure location. They are one time use codes to get into your system in case you lose your phone or such.)

https://www.google.com/chart?chs=200x200&chld=M|0&cht=qr&chl=otpauth://totp/root @sys-craft%3Fsecret%3DSS1ILT719ZXU5ZQH
Your new secret key is: SS1ILT719ZXU5ZQH
Your verification code is 638725
Your emergency scratch codes are:
94411908
27100405
69359811
69102959
04500427

Do you want me to update your “/root/.google_authenticator” file? Yes

Do you want me to update your "/root/.google_authenticator" file (y/n) y

Do you want to disallow multiple uses of the same authentication
token? This restricts you to one login about every 30s, but it increases
your chances to notice or even prevent man-in-the-middle attacks (y/n). Yes

Do you want to disallow multiple uses of the same authentication
token? This restricts you to one login about every 30s, but it increases
your chances to notice or even prevent man-in-the-middle attacks (y/n) y

By default, tokens are good for 30 seconds and in order to compensate for
possible time-skew between the client and the server, we allow an extra
token before and after the current time. If you experience problems with poor
time synchronization, you can increase the window from its default
size of 1:30min to about 4min. Do you want to do so (y/n). No

I answered the above question as no, as I was trying to be more secure. But if you are a slow type, or just want a little more time you can answer yes.

By default, tokens are good for 30 seconds and in order to compensate for
possible time-skew between the client and the server, we allow an extra
token before and after the current time. If you experience problems with poor
time synchronization, you can increase the window from its default
size of 1:30min to about 4min. Do you want to do so (y/n) n

If the computer that you are logging into isn’t hardened against brute-force
login attempts, you can enable rate-limiting for the authentication module.
By default, this limits attackers to no more than 3 login attempts every 30s.
Do you want to enable rate-limiting (y/n) YES

If the computer that you are logging into isn't hardened against brute-force
login attempts, you can enable rate-limiting for the authentication module.
By default, this limits attackers to no more than 3 login attempts every 30s.
Do you want to enable rate-limiting (y/n) y

Now that the questions are answered, you will want to open the google url listed earlier in a browser, this will output a QR code that you can scan with the Google Authenticator app. Once this logon is added it’s time for testing.

Remember to stay logged in to your current ssh session. Open up a new ssh app and connect to your server. If everything goes correctly you should be greeted with the below after you put in your password.

$ ssh root@systemoverload.net
Password:
Verification code:

Troubleshooting

The biggest failure I have seen with this system is time sync issues. If the time is off on the server compared to what is on your mobile phone, you will most likely be denied access. As I stated earlier, it’s best to make sure your server is syncing with a time server before doing this.

Leave a Reply