Using a Yubikey for 2-factor authentication

Security Key NFC by Yubico

For those of you who have not yet encountered a Yubikey, it is a physically small security key which empowers passwordless or 2-factor authentication in a number of different scenarios. They now support a huge number of protocols including One Time Passwords, NFC, FIDO2, U2F, Smart card, and OpenPGP.

Mine has been living on my keyring for several years now, and has proved invaluable for me accessing both my physical and electronic world.

What is Yubikey?

Inserted Yubikey

A Yubikey from Yubico is a small, robust, device which you can carry on your keyring. Once plugged in to a USB port it acts as a simple keyboard emulator – pressing the touch sensitive button on the top will send a stream of characters followed by a carriage return to whichever app is currently active.

This simple emulation generates a OTP (One-Time Password) to the OATH standards. You can see in a terminal window that the OTP changes on each successive generation (note that the first 12 characters I’ve highlighted are always the same and constitute the ID of the Yubikey).

user@host:~# vvfujinjabcdeleuivfiufruftlberifrbjvcffkflne
user@host:~# vvfujinjabcdvvkfugtrrhvnnunbnlgcbjkfgjnduidt
user@host:~# vvfujinjabcdrriktbtuljfjuinhhfkildjlkciegdkr
user@host:~# vvfujinjabcdnbdirdbhdtgiidfkecuueikgkbhbjdlb

The latest products like the Yubikey 5 can do much more than that, but for the purposes of this tutorial we shall concentrate on using the Yubikey with PAM (Linux Pluggable Authentication Modules).


If you have followed my Fail2ban tutorial you will know that servers on a publicly accessible IPs are easy targets for the bots trying to access SSH and other services. Of course strong passwords are your first defence against such attacks, and I’m sure many of you will have configured authorized key access for SSH, but what if you need to be able to shell onto a host from trusted locations where you don’t have your keys?

I will show you below how to configure Yubikey into the SSH PAM stack as a compliment to shared keys. Note: You could lock yourself out of a host if you get this configuration wrong, so I’d strongly suggest having an alternate method of access (e.g. authorized keys) before proceeding.

It is important to remember that the OTP is just one of the authentication factors and the other is your existing system password.

Installation and Configuration

Most modern Linux distributions have the required modules in their package mamagers. I shall be using Debian, but configuration files will be in broadly the same place on Fedora or FreeBSD.

user@host:~# apt-get install libpam-yubico

One of the requirements is to maintain a map between the Yubikey ID and the system username. This file I create as /etc/yubico and should look similar to below.

# Username : Yubikey ID

Obviously your username and ID will differ from mine – to get your key simply plug in your Yubikey, make sure a text editor is the active window and press the button. The first 12 characters generated are your ID. Users can have multiple IDs by adding them all on the same line separated by colons.

The PAM module will by default use the Yubico servers to validate the OTP entered, and any unboxed key will already be know to the servers. But it you have reprogrammed the key for any reason you will need to re-register with the key servers. Note that you do not need the APi key for pam to access the services.

Now insert the following into the top of/etc/pam.d/sshd so that it is the top of the stack. Yubikeys support multiple identifies but we shall use the default for ease.

auth sufficient id=1 authfile=/etc/yubico

Finally, make sure that ssh is properly configured by editing /etc/ssh/sshd_config and making sure that the following settings are enabled

ChallengeResponseAuthentication yes 
UsePAM yes

Restart the ssh service and start testing. If it is a remote host I would suggest keeping one session connected in case you have any issues.

root@host:~# service ssh restart


Fire up a new local terminal and connect to your host (making sure that your Yubikey is plugged in). If you have authorized key access configured then you can bypass that on the command line as follows.

user@host:~# ssh -o PreferredAuthentications=password

and you should be presented with your password prompt. Now enter the system password for the user you are connecting as, then press the button on the Yubikey. The OTP and a carriage return will be sent and you will be logged in's password:




Yubico and YubiKey are registered trademarks of Yubico.