Monday, March 23, 2020

Two Factor Authentification on gitlab with Yubikey

I wanted to have a working Two Factor Authentification (2FA) setup to login on, Debians’s gitlab instance.
You might already know Two Factor Authentification via a One Time Password (OTP) generating app on your smartphone, like FreeOTP or Google Authenticator. But it is possible to use a physical device, and a keypress on the device is enough to authenticate (speed up things !). Here I am using a Yubikey 4, a popular USB device for Two Factor Authentification which is officially supported by gitlab, and whose tooling is well packaged in Debian.

Get to know the device

Install the needed packages to work with the yubikey
# apt install yubikey-manager libu2f-host0
List connected devices on your usb bus:
$ lsusb
Bus 002 Device 109: ID 1050:0407 Yubikey 4 OTP+U2F+CCID
Get info about the device capability
$ ykman info
Device type: YubiKey 4
Serial number: 1234567
Firmware version: 4.3.7
Enabled USB interfaces: OTP+FIDO+CCID
OTP         Enabled             
FIDO U2F    Enabled             
OpenPGP     Enabled             
PIV         Enabled             
OATH            Enabled             
FIDO2       Not available
The capability which interests us here is FIDO U2F. The Yubikey 4 supports Two Factor Authentification via the U2F standard, and this standard is maintained by the FIDO Industry Association, hence the name. As I plan to only use the FIDO U2F capability of the key, I set ‘FIDO’ to be the single mode of the key.
ykman mode FIDO

Testing web browser interaction with Yubico demo system

Now we need to have to have a browser with support for the U2F standard. Firefox has builtin support since Version 67. Debian 10 “Buster” has firefox-esr Version 68, so that will work. For testing yubikeys, the manufacturer has a demo website, where you can test U2F. Go to and follow the “Explore the Yubikey” link.
Once there you will be asked to register an account on yubicom’s demo systems, to which you will add the Yubikey as an Authenticating Device. After that you can add your security key. First step will be to register the device, which will require a light touch on the Yubikey button, and acceptance of this Firefox warning Window, as the demo website wants to know the model of the device.

Firefox message on the yubikey demo site. A normal site with U2F would not require the extended information, and have a simpler popup message.
As soon as the device is registered, you can login and logout and you will be prompted again to lightly touch the Yubikey button to authenticate, in addition to the classical login / password.

Using U2F on gitlab

When you want to register your yubikey for logging on salsa, you need first to register a One Time Password device in Settings -> Account -> Manage two-factor authentication, and Register Universal Two-Factor (U2F) Device. After the usual Firefox Popup, and the light touch on the key button, that'it you have a fast, and reliable Two Factor Authentification !


Each time I have to look on anything close to cryptography / authentification, it is a terminology avalanche. Here we had already 2FA, OTP, U2F, FIDO. And now there is FIDO2 too. It is the next version of the U2F standard, but this time it was named after the standardizing organization, FIDO. The web browser part of FIDO2 is called Webauthn. Also sometimes the whole FIDO2 is called Webauthn too. Easy to get, isn’t it ?

No comments: