In this post I will discuss how you can use your YubiKey security token for two-factor authentication. As an example, I will show you how to configure your YubiKey as a second factor for GitHub and GitLab. This means nobody will be able to log into your accounts without your YubiKey, even if they guessed your password. I bet Gentoo recently wished they had used two-factor authentication.

Preliminary Remarks

The YubiKey is a USB security token made by the company Yubico. It can be used for a variety of cool things, including two-factor authentication, challenge-response authentication, and everything that is based upon PGP.

I recently got myself one such device and I enjoy it quite a bit, both for using it on a daily basis and toying around with it. However, I feel the setup is not always straight forward and hassle-free. So I decided to write about how you can make use of the (to my mind) coolest features of the device.

There is a number environmental factors that are relevant to the setup procedure. Most notably, which YubiKey you own and what operating system you use. I used the YubiKey NEO and Manjaro Linux for everything I describe here. However, almost all of it should be applicable to other YubiKey devices and other Linux distributions as well.

Universal 2nd Factor (U2F)

U2F is an open standard for two-factor authentication. It gives you a security benefit compared to basic username/password authentication by additionally requiring the possession of a second factor, such as a hardware token.

Setting up U2F with the YubiKey in fact quite straight forward. The first step is to make sure that the YubiKey's U2F mode is enabled. Check ykman info (from the yubikey-manager package) for that. This is the default and is most likely the case with your device as well. Follow the instructions of the official guide otherwise.

Next we set up your browser. Install the libu2f-host package. It will create the udev rules required to allow regular users (and your browser) to communicate with the YubiKey. Firefox supports U2F starting from version 57. However, it is not enabled by default. Navigate to about:config and set security.webauth.u2f to true. An up-to-date Chromium should be fine out of the box.

Now let's try it out. Yubico offers a nice demo page. Use an arbitrary username and password -- this is only for demo purposes. You should be asked to touch your key. After that, the demo page will identify your device and show you some technical data. The demo also allows you to test the login, using the username/password combination from before and touching the key again.

Congrats! You're all set up to use your YubiKey as a second factor for real services.

Integration with GitHub and GitLab

As a example, let's use the YubiKey to authenticate towards GitHub and GitLab. Setting up a second authentication factor works very similar for both services.

Both require you to set up two-factor authentication with an app before you can add the YubiKey as another factor. On Android, FreeOTP works pretty well (also available in Play store). In order to configure it, navigate to Settings > Security on GitHub and Settings > Account on GitLab.

After setting up the app as authentication factor you will be able to add the YubiKey as an alternative to the app on the same settings page. Personally, I feel this offers a huge convenience benefit compared to the soft token authenticator app on the phone.

Catches and Pointers

If anything doesn't work, it is a good idea to consult the official guide first. If it turns out that the udev rule is not in place, here are some additional pointers:

• libu2f-host should place it in /usr/lib/udev/rules.d/70-u2f.rules.
• the libu2f-host repository contains some useful instructions as well as the rule file itself
• don't forget to run udevadm trigger in case you need to tweak the udev rules manually.

More About the YubiKey

I am planning to publish a series of posts about what you can do with the YubiKey. Check out all posts tagged with YubiKey :)