How to Enable Two Factor Authentication with pam-u2f

We live in a world where data is an incredibly valuable currency, and you are always at risk of loss. Because of this, you must do everything you can to ensure what you hold on your desktops and servers is safe. If you are looking to lock down your Linux servers and desktops as tight as possible, you should consider to make use of two-factor authentication. By adding two-factor authentication, it becomes much more difficult for malicious users to gain access to your machines. It is possible to configure a machine so that you cannot log into the console or desktop or by way of secure shell, without having the two-factor authentication code associated with that machine.

I have successfully tested this on Ubuntu Linux with Yubico YubiKey 5 NFC and Security Key by Yubico.

Install pam-u2f

First, you need to enable Yubico’s PPA:

sudo add-apt-repository ppa:yubico/stable

Recent versions of add-apt-repository automatically run apt-get update, but if that’s not the case, you will need to run it manually.

Then you will need to install libpam-u2f:

sudo apt install libpam-u2f

If you have a Yubico key, you may need to download 70-u2f.rules into /etc/udev/rules.d/.

Create Authentication Mapping

After that you will need to associate your U2F keys with your account. There are two ways:

1. Central authentication mapping: there will be one system-wide file mapping U2F keys to user accounts;
2. Individual authentication mapping: each user creates their own ~/.config/Yubico/u2f_keys file with key mappings.

Central Authentication Mapping

You will need to create a file, for example, /etc/u2f_keys. The file will have the following format:

<username>:<KeyHandle1>,<UserKey1>
<username>:<KeyHandle1>,<UserKey1>:<KeyHandle2>,<UserKey2>

Individual Authentication Mapping

Same as above, but the file has to be named u2f_keys and be located in ~/.config/Yubico/. The file will obviously contain only one line.

Create Authentication Mapping

To create authentication mapping, you will need to use pamu2fcfg: to do so, you first insert your U2F key, and then run pamu2fcfg. When run, you will need to touch the key when it flashes, and then pamu2fcfg will print something like

volodymyr:Zx...mw,04...0a

The output will be much longer, but for security reasons, I have removed the sensitive parts 🙂

The first field (before colon) is the user login, the second field (till comma) is the key handle, and the third field is the user key. The line pamu2fcfg printed will need to be added to the mapping file.

NB: pamu2fcfg does not add a new line character, therefore if you redirect its output to the mapping file, consider this when using Central Authentication Mapping.

It is wise to have a backup key in order not to get locked in case you lose your first key. Repeat the procedure above, but use pamu2fcfg -n: this will omit the username field, and the output can be appended to the line with your username, like this:

volodymyr:Zx...mw,04...0a:xB...fw,04...3f

Configure PAM

Open /etc/pam.d/service_name (e.g., /etc/pam.d/sudo) and add

auth       required   pam_u2f.so

right after @include common-auth. The file should look something like this:

#%PAM-1.0                                                                                                                                                                                    
                                                                                                                                                                                             
session    required   pam_env.so readenv=1 user_readenv=0                                                                                                                                    
session    required   pam_env.so readenv=1 envfile=/etc/default/locale user_readenv=0                                                                                                        
@include common-auth                                                                                                                                                                         
auth       required   pam_u2f.so                                                                                                                                                             
@include common-account                                                                                                                                                                      
@include common-session-noninteractive

If you use Central Authentication Mapping, you will need to tell pam_u2f which file to use:

auth       required   pam_u2f.so authfile=/etc/u2f_keys

Tips and Tricks

• When not all users on the system are required to use U2F, add the nouserok option to have the PAM module continue if the user is not mentioned in the authorization mapping file: auth required pam_u2f.so nouserok;
• If you often forget to insert the key, prompt option will help: this will make pam_u2f print Insert your U2F device, then press ENTER. and give you a chance to insert the key;
• If you would like to be prompted to touch the device, cue option will help: this will make pam_u2f print Please touch the device. message.