Add Two-Factor-Authentication to SSH on Debian Wheezy to Stretch

Introduction

This guide shows you, how you can add 2FA to your OpenSSH on Debian Wheezy, Jessie and Stretch using Google Authenticator. We assume that your SSH already uses Pubkey-Authentication while PasswordAuthentication is disabled.
Also this guide should also work on Debian's derivates and maybe other distros.

Limitations

I have only tested this on Wheezy and Stretch but Jessie should work exactly like Stretch.
Also OpenSSH on Debian Wheezy is by default too old for 2FA but we can use the backported OpenSSH-Server for that.

Install backported OpenSSH to Wheezy

Just run the following commands to install the Wheezy backports to your system. All commands are supposed to be executed with root or using sudo:

~$ echo "deb http://ftp.debian.org/debian wheezy-backports main" > /etc/apt/sources.list.d/backports.list
~$ apt-get update
~$ apt-get -y -t wheezy-backports install openssh-server

When it asks to overwrite /etc/pam.d/sshd say Yes.

Install Google Authenticator ...

If you want to be able to scan the QR-Code with your favorite 2FA-App directly from the terminal you might also want to install the following package:

~$ apt-get -y install libqrencode3

... on Wheezy

We need to install the Google Authenticator for Jessie, so we don't have to built it from source:

~$ cd /tmp
~$ wget http://ftp.us.debian.org/debian/pool/main/g/google-authenticator/libpam-google-authenticator_20130529-2_amd64.deb
~$ dpkg -i libpam-google-authenticator_20130529-2_amd64.deb

... on Jessie and Stretch

For Jessie and Stretch this is straightforward. Install it with

~$ apt-get -y install libpam-google-authenticator

Configure OpenSSH

Since we now have the newest OpenSSH installed, the configuration is identical now.

At first edit /etc/pam.d/sshd and search for @include common-auth, which should be right at the top of the file. Comment it out and add the following directly below:

...
# Standard Un*x authentication.
#@include common-auth
auth required pam_google_authenticator.so nullok
...

Now we need to edit the ssh server config at /etc/ssh/sshd_config.

Search and enable the following line, or add it if it's not there

ChallengeResponseAuthentication yes

Also add the following line right beneath, so after a successful Pubkey-Authentication, we're getting asked for our 2FA Verification Code:

AuthenticationMethods "publickey,keyboard-interactive"

Save the file and now restart your SSH server with service ssh restart.

Enable Google Authenticator for a user

Remember the line above, where we added the nullok option to the added line in /etc/pam.d/sshd? This says that Pubkey-Logins to users without a configured Google Authenticator are being allowed without the Verificaton Code until it's configured once.

We will configure it now!

Login with the desired user or change to that user with su - <username> and run the following command. I don't need to explain the options, the Google Authenticator asks you and they're well explained. My advice is to say Yes to all of them for increased security.

Run the following commands:

~$ google-authenticator
Do you want authentication tokens to be time-based (y/n) y
# Here it will show you the QR-Code, Secret-Key and Recovery-Codes. Save them or add them to your 2FA-App on your mobile phone
# Afterwards just say 'y' to all following questions

Now you're done. As soon as you logout and login again, you should be asked for a Verification Code: where you need to type in your new 2FA Code and you're in!

Conclusion

Adding 2FA is quite simple and increases the security of your SSH Server. Maybe you should add another user for a fallback SSH Login first when you do it for the first time.

A nice side-effect of using a newer OpenSSH on Wheezy is also that you can now use ED25519 Keys for Pubkey-Authentication instead of RSA-Keys.