Banner image of Yubico Security Key: Local 2FA with PAM

Some time ago, we compared the YubiKey 4C and the Nitrokey Pro that we both use on a daily basis. This time, we show you how you can use a Yubico Security Key with the pluggable authentication module (PAM) on Linux for local two-factor authentication (2FA).

Always stay in the loop!
Subscribe to our RSS/Atom feeds.

What is U2F, FIDO, FIDO2, and WebAuthn?

Universal 2nd Factor (U2F) is an open authentication standard originally developed by Yubico and Google and now hosted by the FIDO Alliance. Security devices with U2F support allow you to use two-factor authentication more easily since you don't need to manage additional credentials. Read our comparison of the YubiKey 4C and Nitrokey Pro for more information on U2F for two-factor authentication.

The Fast IDentity Online Alliance (FIDO Alliance) consists of different companies which recognized that security tokens for strong authentication lack interoperability. Their aim is to provide widely-accepted specifications to make the usage of online services more secure. The FIDO Alliance published two different specifications:

  • UAF: Universal Authentication Framework (no passwords or user interaction involved)
  • U2F: Universal 2nd Factor (using a security token as a second factor)

A newer project of the FIDO Alliance is FIDO2. FIDO2 connects the new W3C Web Authentication standard (WebAuthn) with FIDO's Client-to-Authenticator Protocol (CTAP). The goal is to enable users to authenticate to online services by using their security devices (mobile and desktop). For more details, read our comparison of the Yubico Security Key and Nitrokey FIDO2.

To put it in a nutshell, U2F offers public key-based two-factor authentication. In addition to this, FIDO2/WebAuthn offers strong single-factor authentication and different authenticator types.

Requirements

For this tutorial, you need:

  • a U2F security token. We use a Yubico Security Key, but you can use any other U2F token.
  • your Linux device (we use Arch Linux in this guide).

Step 1: Download and install pam_u2f

First of all, we have to install pam-u2f. This is a PAM module that implements U2F. You can use this module for all U2F security tokens not only for YubiKeys. Arch users can install it by entering: sudo pacman -S pam_u2f. This also installs Yubico's U2F Server and Host C libraries (libu2f-host and libu2f-server).

At this point, you can check whether your system recognizes the YubiKey: dmesg | grep -i "Yubico Security Key". This shows “… USB HID v1.10 Device [Yubico Security Key by Yubico] …". If your device doesn't recognize the YubiKey, reboot it. If you have the official YubiKey Manager on your system, you can also run: ykman info.

Step 2: Use pamu2fcfg to generate your config

After installing pam-u2f, you can use pamu2fcfg to easily generate a configuration file that we will add to the PAM configuration later.

Run pamu2fcfg. The physical button of the Security Key blinks now. Press the button of the YubiKey to proceed. You will immediately see an output like “[username]:[key-handle],[public-key]” in your terminal.

Open your favorite text editor and save this output in a file which is accessible for the user (e.g., in the home folder of the user). We will put it in ~/.config/Yubico/u2f_keys since there is already a Yubico folder and u2f_keys is the default location for this PAM module's auth file.

Advanced users can directly redirect the output of pam-u2f to the file by entering: pamu2fcfg > ~/.config/Yubico/u2f_keys.

Step 3: Update your PAM file

Finally, we have to tell PAM to use our U2F security key. You can either create a new file in /etc/pam.d/ or edit an existing file. We will edit /etc/pam.d/gdm-password here to use U2F with the GNOME Display Manager (GDM).

Add auth sufficient pam_u2f.so debug to the file and save it. The debug keyword enables debug output in case of any errors. Log out and test whether you can log in with your U2F key and/or password.

In case of success, remove debug, and change sufficient to required. The difference is explained below:

  • sufficient: This is a PAM keyword telling PAM that if this module succeeds, all following sufficient modules are also satisfied. In our case, PAM will accept:
    • only our password (single factor)
    • only our U2F token (single factor)
    • both factors (if the U2F token is connected with the device when GDM asks for the password)
  • required: This enforces usage of the U2F token and enables true two-factor authentication.

Save the file, and log out again.

Optional: Use U2F for sudo

In order to use U2F for sudo, you only need to add the line auth required pam_u2f.so to /etc/pam.d/sudo. This results in exactly the same behavior as with gdm-password.

Optional: Get prompted to insert your security token

Using the configuration above, there is no visual indication to insert your security token when you log in. This can be changed by adding the keyword interactive to the end of the line. For instance: auth required pam_u2f.so interactive.

Using this for sudo results in the prompt “Insert your U2F device, then press ENTER.” in the Gnome Terminal and/or in GDM.

Optional: Add a second U2F key

There is the risk of losing or destroying the U2F token. We recommend to use a second one as a backup. You have to run step 2 again but this time you press the button of the backup device. The result is similar output as before. You need to append this to the previous output.

Change the string in ~/.config/Yubico/u2f_keys to “[username]:[key-handle],[public-key]:[backup-key-handle],[backup-public-key]” and test it again.

Follow us on Mastodon:
@infosechandbook

Summary

In this article, we showed several examples for using a U2F security token. The new WebAuthn standard has the potential to spread acceptance of such tokens on the internet making credential management less painful.

Changelog

  • Dec 23, 2019: Removed aurman (package is now official). Clarified differences between U2F und FIDO2/WebAuthn. Changed sufficient to required as recommended (real two-factor authentication). Removed section on other U2F tokens since this is already mentioned.
  • Apr 22, 2019: Added sections about using U2F for sudo, and getting a visual prompt.
  • Nov 3, 2018: Updated information about Nitrokey FIDO U2F.

See also