Setup Yubikey 2FA on Ubuntu

I have recently been on a Yubikey kick lately and have been finding ways to enable it on my devices. If you want to use Yubikeys for ssh authentication, this quick walkthrough will show you how to set it up on Ubuntu.

Obtain Yubico API Key Information

To get started, you’ll need to take your Yubikey and obtain an API key. Yubico makes this really simple here:
https://upgrade.yubico.com/getapikey/

Install Required Packages

	sudo apt update
	sudo apt install libpam-yubico

view raw install_dependencies_yubikey hosted with ❤ by GitHub

Update sshd_config

Using your editor of choice, modify /etc/ssh/sshd_config.

sudo vim /etc/ssh/sshd_config

view raw edit_sshd_config hosted with ❤ by GitHub

You’ll want to add/modify the following lines to be reflected in your file.

	KbdInteractiveAuthentication yes
	ChallengeResponseAuthentication yes
	PasswordAuthentication yes
	UsePAM yes

view raw sshd_yubikey_configuration hosted with ❤ by GitHub

Save and exit the file editor once this is complete.

Update pam.d sshd

sudo vim /etc/pam.d/sshd

view raw edit_pam_sshd hosted with ❤ by GitHub

Using the Client ID and Secret key obtained from Yubico, add the following at the top of your file.

auth required pam_yubico.so id=<Client ID> key=<Secret Key> authfile=/etc/yubikey_mappings mode=client

view raw pam_sshd_configuration_yubikey hosted with ❤ by GitHub

Save and exit the file editor once this is complete.

Create Yubikey Authfile

sudo vim /etc/yubikey_mappings

view raw open_yubikey_mappings hosted with ❤ by GitHub

This file will be used to specify which users and key(s) will be used. For each line of the file, add your desired user and the first 12 characters produced by your yubikey when pressed. Consider the following example mappings file:

	user:kfibugjrendje
	user2:kbmgjrtufjeh:kbjfmsjehfjg

view raw yubikey_mappings_example hosted with ❤ by GitHub

This setup has two users setup to use yubikeys. user can be authenticated with only one key. user2, however, can be authenticated with two separate keys. To add additional keys, simply extend the colon separated 12-character values for your keys.

Restart Service

Warning: Once this is complete, I highly recommend you do not close your current session. I would recommend opening another terminal and testing your authentication works as expected to avoid locking yourself out.

sudo systemctl restart sshd

view raw sshd_restart hosted with ❤ by GitHub

Testing

To verify everything worked, ssh into your box and you should be prompted to enter both Yubikey and Password.

Conclusion

You may have noticed that this tutorial has you setting up Yubikey + Password for authentication. I personally prefer to require password + Yubikey for authentication on my systems, however, everyone’s risk tolerance is different. If you want to modify this setup to only authenticate with Yubikey, you can do that by disabling the password authentication in your sshd configuration.

Another thing worth mentioning is that if you’re planning to use Yubikeys, you should look into having backups stored in safe locations. This is a good idea in the event that you lose your primary Yubikey.