Enable 2FA SSH for Mac
I’ve been using two-factor authentication with Authy now for awhile and have really enjoyed the flexibility of being able to control all of my logins with 2FA. I got to thinking to myself “Wouldn’t it be cool if I could use 2FA on my SSH logins?”
Well, it turns out that you can! I recently followed a tutorial by servinglinux.com and with little adaptation was able to get 2FA working beautifully on my Macs.
However, there are some Caveats:
- You will need physical access to the Mac. You will be rebooting SSH as part of this tutorial, and if something goes wrong SSH may end up broken.
- You will need to disable System Integrity Protection to install the Google Authenticator PAM. You don’t need to have it disabled to have it running, just to install it.
- You will need to install Xcode, homebrew, and a couple of third-party libraries to build the PAM for your version of macOS.
Console access is preferred while setting this up since we will end up needing to restart the
sshd
service at some point, which will drop your SSH connection.
- First of all, you will need Xcode installed to get the Xcode command line tools. if you don’t have Xcode installed already, run the following to start that installation:
xcode-select --install
- Install homebrew on your Mac if you haven’t already. It’s best practice to have it installed anyway. We’ll need it to install some things here down the line.
- Disable SIP on your Mac if you haven’t already. You will get errors later on if it is enabled for the installation. (You can turn it on after the installation is successful.)
- Now we’re ready to download the Google Authenticator server module to build. cd into your working directory and clone down the module with the following:
git clone https://github.com/google/google-authenticator-libpam
cd
into the google-authenticator-libpam directory.- Now we’ll need to install two libraries that are needed to build Google Authenticator for your version of macOS. They are autoconf and libtool. Your version of libtool may work with Google Authenticator, but mine didn’t so I had to install libtool from brew.
brew install automake autoconf libtool
- Once those have finished installing we are able to build the Google Authenticator PAM. PAMs (Pluggable Authentication Modules) are a really cool way of adding authentication functionality to your ‘nix system. This module will plug into the authentication system of SSH. As long as you are in the google-authenticator-libpam directory and your brew was able to pull the packages above, go ahead and build it:
./bootstrap.sh
./configure
make
make install
(You should be able to ignore most of the warning that are generated when you build this. Send me a message if you have problems with it and I’ll be happy to look at it with you.) - Copy the built PAMs into the /usr/lib/pam directory:
sudo cp /usr/local/lib/security/* /usr/lib/pam
- Now we need to add the Google Authenticator module to the list of PAMs that are available for SSH to authenticate with. Edit the sshd PAM file with
nano
orvi
:sudo nano /etc/pam.d/sshd
- Add the following line to the end of the file:
auth required pam_google_authenticator.so
- Save the file, and restart the SSH server with the following command (it will restart by itself):
sudo launchctl stop com.openssh.sshd
- Now we are ready to setup the Google Authenticator service. This will need to be done for every user that you want to be able to SSH into. Start the setup process by running the following in the account you want to SSH with:
google-authenticator
- You will be prompted to save your settings to your home folder, configure the number of authentication attempts allowed, the number of 2FA codes to accept, and how rate-limiting should work. Go ahead and configure it to your liking. If you want to change the settings, you will have to delete ~/.google_authenticator and run the command again.
- You will be given the emergency scratch codes for the account, so make sure you keep these somewhere secure. They will help you fix 2FA if it ever breaks. You will also be given a code to input to Google Authenticator or Authy to authenticate your logins.
- Try it out!
ssh localhost
and see if it works. If you followed the steps you should be prompted to input a verification code after your password. Remember that you will have to run the google-authenticator setup for any new user you want to have the ability to SSH into your Mac.
Let me know in the comments if you have any problems, or suggestions of how to improve the process!