What is Yubikey?
YubiKeys are small USB dongles that you can plug into your computer. They can simulate keyboard input, allowing you to enter One Time Passwords (OTPs) with the press of a button to authenticate with services like Google, Dropbox and GitHub.
YubiKeys can also be used when logging into a remote server. This guide will show you how to configure your server so that a YubiKey must be plugged in and tapped in order to log in to your server using
ssh. Depending on your needs, you can also configure a password in addition to the YubiKey for an extra level of security.
If you want to work through this guide but don’t have a YubiKey, you can find one at this link. As of this writing, any key that supports ‘Yubico OTP’ will support two-factor SSH authentication.
Before You Begin
- This guide will use
sudowherever possible. You should create a standard user account, harden SSH access and remove unnecessary network services.
- Update your local system. Then update your server using the following:
sudo apt-get update && sudo apt-get upgrade
- Test your YubiKey at demo.yubico.com to make sure it’s working correctly.
Configure Your YubiKey
If your YubiKey still has its default configuration, you can skip this step. If you’ve made some changes, this section will tell you how to put the appropriate configuration for this guide onto slot 1 of your YubiKey. If you want to use a different slot, make sure you select it instead of slot 1 in the following instructions.
- Install the YubiKey Personalization Tool for your system and open it.
- Click on the ‘Yubico OTP’ menu in the top-left corner, and select ‘Quick’. Your screen should look like the one below.
- Click ‘Write Configuration’. Click ‘Cancel’ on the pop-up window that asks where to save the log file.
- Now select ‘Upload to Yubico’. In the web form that opens, fill in your email address. Select the field asking for an ‘OTP from the YubiKey’ and touch the button on your YubiKey (or touch and hold if you programmed slot 2). This should fill the field with a string of letters. Complete the captcha and press ‘Upload AES key’.NoteThe page will respond with a table containing your key information. You should keep this data in a safe place. Should you ever lose your YubiKey, you will need this data to reconfigure a new one with the same settings.
- Test that your key works by following the instructions for single-factor authentication on demo.yubico.com. If it doesn’t, you may need to wait up to 15 minutes for your key to process on their servers.
Install the Authentication Software
- Register for an API key here, by entering your email address and (with the ‘YubiKey one time password’ field selected) touching the button on your YubiKey. Keep the Client ID and Secret Key returned by the website.NoteOn Ubuntu, you may need to install
python-software-propertiesto add the repository.
- On your Server, install the
sudo add-apt-repository ppa:yubico/stable sudo apt-get update sudo apt-get install libpam-yubico
On Debian (Wheezy):
sudo apt-get install libpam-yubico
On Fedora/EPEL/Arch Linux:
sudo yum install pam_yubico
Yubico’s documentation also has instructions on how to build
You may need to move
pam_yubico.soto wherever PAM modules are stored on your system (usually
lib/security). The Ubuntu package will automatically install the module in the appropriate location, but you can check to see whether it’s in the right location with
ls /lib/security. It may also be stored in
/usr/local/lib/security, in which case you will need to move it manually.
- Create the file
sudo touch /etc/ssh/authorized_yubikeys
- Populate this file with the usernames for which you want to enable two-factor authentication and their YubiKey IDs. You can obtain the ID by opening a text editor and touching the button on the YubiKey, and selecting only the first 12 characters. The first line below would be a typical configuration. The subsequent lines show a configuration where users
user4use multiple YubiKeys and plan to access the server with all of them./etc/ssh/authorized_yubikeys
user1:vvklhtiubdcu user2:ccurrufnjder:ccturefjtehv:cctbhunjimko user3:ccdvnvlcbdre:vvvglinuddek user4:vvddhfjjasui:vvfjidkflssd
auth required pam_yubico.so id=<client id> key=<secret key> authfile=/etc/ssh/authorized_yubikeysto the start of
<client id>with the ID you retrieved when applying for an API key, and
<secret key>with the secret key. If you only want single-factor authentication (either a YubiKey or a password), change
sufficientto tell the system that a valid YubiKey will be enough to log in./etc/pam.d/sshd
# PAM configuration for the Secure Shell service # Add your line below this one # v v v v v v auth required pam_yubico.so id=client id key=secret key authfile=/etc/ssh/authorized_yubikeys # ^ ^ ^ ^ ^ ^ # Add your line above this one # Standard Un*x authentication. @include common-auth
On some systems, like Arch Linux, you will need to edit
/etc/ssh/sshd_config, add or edit the following settings:/etc/ssh/sshd_config
UsePAM yesIf you want to only use a YubiKey for single-factor authentication, set
- Restart the sshd daemon to allow the changes to take effect:
sudo systemctl restart sshd
Test the YubiKey
exit ssh email@example.com
Depending on your setup, you may be prompted for your YubiKey. All you need to do is touch the button; it will enter the key for you. Then, type in your password if you are using multi-factor authentication. It will look something like the image below.
You can now log into your server.
If you encounter any problems, make sure you’ve followed all of the steps in this guide and restarted your server. If these steps don’t solve your issues, you can enable logging, by following these steps:
- Add the word
debugto the end of the line you added in
auth required pam_yubico.so id=<client id> key=<secret key> authfile=/etc/ssh/authorized_yubikeys debug
- Create a debug log file:
sudo touch /var/run/pam-debug.log sudo chmod go+w /var/run/pam-debug.log
- Log data to this file:
sudo journalctl -f -l tail -f /var/run/pam-debug.log
- Log in again and analyze this file for clues as to what is causing the problem.
- Once you’re done, disable debugging by removing the
/etc/pam.d/sshd. Then, delete the log file.