How to configure YubiKey on Linux using U2F function

With the help of YubiKey hardware security keys, your system receives an increased level of protection, and the process of logging into accounts becomes faster and more convenient. To easily configure the necessary parameters on a Linux system, you should follow the instructions below.

Setting up the YubiKey in a Linux environment is slightly different from setting up in other operating systems such as Windows. First, you’ll have to do things through the terminal, not the GUI, for setup. Second, you’ll need to make a few adjustments to prevent attackers from bypassing certain restrictions. At the same time, it is important that you do not block yourself from accessing the system.

Steps to be followed:

• installing Yubico software;
• setting up and binding the YubiKey security key;
• setting up the system to use keys;
• elimination of possible malfunctions.

If you plan to use Security Key or YubiKey Bio series keys, please follow the U2F (Two-Factor Authentication) key setup instructions below.

Compatible keys

To configure the YubiKey using the U2F function, you can use keys of any series available in our online store, even Security Key and YubiKey Bio.

Ways to install Yubico software

There are several ways to install Yubico software on Linux. For example:

• Installing Yubico Authenticator:
• Installing the YubiKey Manager.
• Using built-in repositories.
• Using PPAs from Yubico.
• Compilation from the source code.

More information in the article: “How to install Yubico software on Linux”.

Configuring the YubiKey security key

Consider configuring the YubiKey on an Ubuntu system using the U2F feature in the Security Key or YubiKey Bio series (or others). Based on this example, you will be able to make similar settings in systems similar to Ubuntu.

1. Open a terminal and run the command that installs the appropriate software in Ubuntu: sudo apt-get install libpam-u2f.
2. Insert the Security Key or YubiKey Bio.
3. First run the command mkdir -p ~/.config/Yubico, then pamu2fcfg > ~/.config/Yubico/u2f_keys. The system may then ask for a PIN code to activate the FIDO2 function.
4. When the key starts flashing, tap it to confirm your presence.

In order not to lose access to your personal device if the key is lost, add a backup security key. To do this, insert an additional key, run the command in the terminal pamu2fcfg -n >> ~/.config/Yubico/u2f_keys and tap the key when it flashes. If you don’t have a spare key yet, you can skip this step and come back to it later.

For an added layer of security, you’ll also need to move the file u2f_keys to a safer place. Where you need sudo permission to edit a file (eg /etc).

For this:

1. Create a directory (folder) named Yubico (eg /etc/Yubico).
2. Move the file from ~/.config/Yubicotothe folder /etc/Yubico, by running the command: sudo mv ~/.config/Yubico/u2f_keys /etc/Yubico/u2f_keys.

After the file u2f_keys will be moved to a safe location, you will need to modify the PAM file as well so that the u2f PAM module can find it later. This is done by adding “authfile=/etc/Yubico/u2f_keys” to the end of the file line pam_u2f.so inside the file required for authentication. It is usually located at /usr/lib/x86_64-linux-gnu/security/pam_u2f.so, but it may vary depending on the settings.

Note that, that after performing these actions, you will lose the ability to modify the file without the key, which may lead to the loss of access to your device. Therefore, we do not recommend performing this step without having a backup security key.

Configuring the system to use security keys

In this section, we will consider how to configure the keys for the entrance and the terminal and at the same time not to block the entrance. We will also consider how to adjust the system in case of errors.

Checking the configuration using the sudo command

The sudo command is used to test that a user does not accidentally lock out their computer. To use it:

1. Open the terminal and enter the command: sudo nano /etc/pam.d/sudo.
2. After the answer, find the line «@include common-auth» and add the line to it: auth required pam_u2f.so

Pay attention! If you moved the u2f_keys file to the /etc/Yubico/u2f_keys for increased security, then you will need to add the authentication file and PAM configuration path like this: auth required pam_u2f.so authfile=/etc/Yubico/u2f_keys.

1. Next click Ctrl+O, and then Enterto save the settings. At the same time, do not close the terminal window until the settings are complete.
2. Open a new terminal and enter the command: sudo echo test. The program should prompt you to enter a password. Enter the password and click Enter.
1. Please note that without an inserted YubiKey U2F, authentication will not occur. If it passes successfully, it means that the U2F PAM module is not installed, or there are errors in the file /etc /pam.d/sudo, which you changed.
3. Insert the YubiKey, open a new terminal and type the command again: sudo echo test. Enter your password when prompted. After that, you will see the key flashing. Touch its metal part to reveal your presence.

If U2F authentication is successful after completing all the steps, it means that you have everything set up correctly. So you can move on to the next step.

Note: If you don’t want to be prompted for a key when you run sudo, remove the line you just added to the file /etc/pam.d/sudo.

Adding similar sudo commands to request a security key

Because the sudo states have different authentication paths in different OS versions, you may need to edit a different directory to configure the PAM information file and make it valid.

List of editable files to configure authentication available in Ubuntu 22.04.

Find the file you want and add the following line below the “@include common-auth” entry: auth required pam_u2f.so.

Note. If you moved the u2f_keys file to /etc/Yubico/u2f_keys, then you will need to add the authentication file and path to the PAM configuration as follows: auth required pam_u2f.so authfile=/etc/Yubico/u2f_keys.

After saving your changes, you need to configure your system to require the YubiKey when using this app.

Configuring the system for a remote key when entering the system

1. Open the terminal and enter the command: sudo nano /etc/pam.d/gdm-password. You should receive an answer:

#for Password + YubiKey

Add the line below the “@include common-auth” line.

@include yubico-required

#for YubiKey only

Add the line above the “@include common-auth” line.

@include yubico-sufficient

1. After that, press Ctrl+X, then Enter, to save the settings.

System settings on demand when using the terminal

1. Open a terminal and run the command: sudo nano /etc/pam.d/login.
2. Add the line after “@include common-auth”: auth required pam_u2f.so

Pay attention! If you moved the u2f_keys file to /etc/Yubico/u2f_keys, then you will need to add the authentication file and path to the PAM configuration as follows:​​ auth required pam_u2f.so authfile=/etc/Yubico/u2f_keys.

1. Press Ctrl+X, then Enter —to save your settings and close the file.

After doing these steps, you won’t be able to log in without U2F.

Elimination of possible malfunctions

If you’re having trouble logging in but can’t find the cause, enable debugging in the Yubico PAM module. This way you can track errors.

For this:

1. Open a terminal and run the command sudo touch /var/log/pam_u2f.log
2. If your system is Ubuntu 17.10 or later, run: sudo nano /etc/pam.d/gdm-password. If your system Ubuntu 17.04 or older, run: sudo nano /etc/pam.d/lightdm
3. Add an entry«debug debug_file=/var/log/pam_u2f.log» at the end of the line that contains pam_u2f.so.

After doing these steps, all your subsequent events will be saved to the file /var/log/pam_u2f.log.

This completes our instruction. If you have not yet chosen a dongle or are looking for an additional hardware device, we recommend that you take a look at the offers available in our online store. If you have any questions about key compatibility, please contact our managers.

Similar materials in the Knowledge Base