Setting up SSH 2FA using TOTP
I spend a lot of time connected to remote hosts. My email and IRC client live on a dedicated server with Bytemark, which makes it easy to access wherever I am in the world. I have a well connected VM for running Debian package builds on using sbuild. At home my Home Assistant setup lives in its own container. And of course that lives on a server which is in the comms room and doesn’t even have a video card installed. At work my test machines are all in the server room rather than noisily on my desk. I connect to all of these with SSH (and screen, though I keep meaning to investigate tmux more thoroughly) - I’ve been doing so since the days of dialup, I’m very happy with the command line and I generally don’t need the overhead of a remote GUI. I don’t think I’m unusual in this respect (especially among people likely to be reading this post).
One of the things I love about SSH is the ability to use SSH keys. That means I don’t have to remember passwords for hosts - they go in my password manager for emergencies, I login with them once to drop my .ssh/authorised_keys
file in place, and I forget them. For my own machines, where possible, I disable password logins entirely. However there are some hosts I want to be able to get to even without having an SSH key available, but equally would like a bit more security on. A while back I had a conversation with some local folk about the various options and decided that some sort of two-factor authentication (2FA) was an appropriate compromise; I was happy to trust an SSH key on its own, but for a password based login I wanted an extra piece of verification. I ended up putting the Google Authenticator on my phone, which despite the name is actually a generic implementation of the TOTP and HTOP one-time password algorithms. It’s turned out useful for various websites as well (in particular at work I have no phone coverage and 2FA on O365. Having Authenticator installed makes that easier than having to wave my phone near the window to get an SMS login token).
For the server side I installed the Google Authenticator PAM module, conveniently available in Debian with a simple apt install libpam-google-authenticator
. I added:
auth required pam_google_authenticator.so nullok
to /etc/pam.d/sshd
below the @include common-auth
line, and changed
ChallengeResponseAuthentication no
in /etc/ssh/sshd_config
to be yes
instead. servicectl restart sshd
restarts SSH and brings the new config into play. At this point password only logins are still ok (thanks to the nullok
above). To enable 2FA you then run google-authenticator
as your normal user. This asks a bunch of questions - I went for TOTP (i.e. time based), disabled multiple uses and turned on the rate-limiting. The tool will display an ASCII art QR code (make sure your terminal window is big enough) that can be scanned by the phone app. From this point on the account will require an authentication code after a successful password entry, but also allow SSH key only logins.
For the avoidance of doubt, this does not involve sending any information off to Google or any other network provider. TOTP/HOTP are self contained protocols, and it’s the scanning of the QR code/entering the secret key at setup time that binds the app to the server details. There are other app implementations which will work just fine.
(This post mostly serves to document the setup steps for my own reference; I set it up originally over a year ago and have just had to do so again for a new machine.)