1. Yubico
  2. Business
  3. Guides

Ubuntu Linux login guide (U2F)

Avatar
Clay Degruchy
Created - Updated

This article focuses on Ubuntu Linux, but may also apply to Ubuntu derivatives (e.g. Lubuntu, Xubuntu), and potentially other Debian-based distributions. If you are interested in setting this up on your non-Ubuntu system, additional guidance can be found here.

 

exclamation-triangle-icon.svg Warning: In order to mitigate CVE-2025-23013, Yubico highly recommends ensuring your version of pam_u2f is at least 1.3.1. The newest version is available here.

 

1 Introduction

This guide covers how to secure a local Linux login using the FIDO U2F feature on YubiKeys and Security Keys. This does not work with remote logins via SSH or other methods. The commands in the guide are for an Ubuntu (or Ubuntu based) system, but the instructions can be adapted for any distribution of Linux. See here for an article focused Red Hat and its derivatives, which utilizes challenge-response rather than FIDO U2F.

 

2 Installing the required software

  1. If you haven’t already, enable the Yubico PPA and follow the steps in Using your YubiKey with Linux
  2. Open Terminal
  3. Run the following command: 
    sudo apt-get install libpam-u2f

3 Associating the YubiKey(s) with your account

  1. Open Terminal
  2. Insert your FIDO U2F-capable YubiKey
  3. Run the following command: 
    mkdir -p ~/.config/Yubico
  4. Run the following command: 
    pamu2fcfg > ~/.config/Yubico/u2f_keys
    • You may be prompted for a PIN when running pamu2fcfg. If you are, note that this is your YubiKey's FIDO2 PIN you need to enter. For more information, refer to Understanding YubiKey PINs.
  5. When your device begins flashing, touch the metal contact to confirm the registration

If you have backup devices, use the steps below to associate them with your account. If you do not have a backup device available at this time, you can add one later using the steps below as long as you still have access to your account.

exclamation-triangle-icon.svg Warning: Having a backup device is strongly recommended so that if your device is lost or broken, you will not be locked out of your computer.

 

  1. Open Terminal
  2. Run the following command: 
    pamu2fcfg -n >> ~/.config/Yubico/u2f_keys
  3. When your device begins flashing, touch the capacitive touch sensor on your YubiKey contact to confirm the association

If you would like to add an additional layer of security, you can change the output of the u2f_keys file to an area of the OS where you need sudo permission to edit the file (e.g. /etc). After creating a directory named Yubico (e.g. /etc/Yubico). You can then move the file from ~/.config/Yubico to /etc/Yubico by running the following command:

sudo mv  ~/.config/Yubico/u2f_keys /etc/Yubico/u2f_keys

 

Once the u2f_keys file is moved to a safer location, the PAM file will need to be modified so that the PAM-U2F module can find the u2f_keys file. This is done by adding authfile=/etc/Yubico/u2f_keys to the end of the line of file for pam_u2f.so within the file needed for authentication. This is normally found on the path /usr/lib/x86_64-linux-gnu/security/pam_u2f.so, but this could be different depending on setup.

exclamation-triangle-icon.svg Warning: Please note that once you modify the /etc/pam.d/sudo file to require the  YubiKey, if you were to lose or misplace the YubiKey, you will not be able to modify or change the file to remove the YubiKey requirement.

 

exclamation-triangle-icon.svg Warning: By enabling using this process, if the files are not readable by users, it will cause you to be locked out of your system. The most common cause is an encrypted /home/ folder which will not be readable by root. This will cause you to be locked out once you reset the machine.

 

4 Configuring the system to use the YubiKey

4.1 Test configuration with the sudo command

This section covers how to require the YubiKey when using the sudo command, which should be used as a test so that you do not lock yourself out of your computer.

  1. Open Terminal
  2. Run the following command: 
    sudo nano /etc/pam.d/sudo
  3. Add the line below after the “@include common-auth” line:
    auth       required   pam_u2f.so
manual-icon.svg Note:  If you have moved the u2f_keys file to /etc/Yubico/u2f_keys as mentioned in section 3, you will need to append authfile and a path to the PAM configuration, as shown below:
auth       required   pam_u2f.so authfile=/etc/Yubico/u2f_keys
  1. Press Ctrl+O and then Enter to save the file. Be sure you do not close the Terminal window, otherwise you will not be able to revert the changes.
  2. Remove your YubiKey from the computer
  3. Open a new Terminal window
  4. In the new Terminal window, run the following command:
    sudo echo test
    When prompted, enter your password and press Enter. 
    • Even with the correct password, the authentication should fail as the YubiKey is not plugged in. If the authentication succeeds without the YubiKey, that indicates the PAM-U2F module was not installed or there is a typo in the changes you made to /etc/pam.d/sudo. 
  5. Insert your YubiKey
  6. Open a new Terminal window and run the following command:
    sudo echo test
    When prompted, enter your password and press Enter. Then, touch the capacitive touch sensor on your YubiKey when it begins flashing.

If the password was accepted this time, you have configured the system correctly and can continue on to the next section for requiring the YubiKey to log in. 

bulb-light-icon.svg Tip: If you do not want to require the YubiKey to run the sudo command, remove the line you added to the /etc/pam.d/sudo file.

 

4.1.1 Adding other commands like su for requiring YubiKey login

The PAM module differentiates between various states of the command sudo as they have different authentication pathways. This means that depending on your version you may have to edit another file with the PAM information to make it valid. In Ubuntu 22.04, the following commands have the following files you can edit to add authentication:

 

Command                                                                      File Location

su /etc/pam.d/su
sudo -i /etc/pam.d/sudo-i

 

Add the line below after the @include common-auth line in the file of the command you want:

 

auth       required   pam_u2f.so

 

manual-icon.svg Note: If you have moved the u2f_keys file to /etc/Yubico/u2f_keys as mentioned in section 3, you will need to append authfile and a path to the PAM configuration, as shown below:
auth       required   pam_u2f.so authfile=/etc/Yubico/u2f_keys

After you save the changes, you should now require the YubiKey to authenticate when using the command selected. 

 

4.2 Configuring the system to require the YubiKey for login

  1. Open Terminal
  2. If your system is Ubuntu 17.10 or newer, run the following command: 
    sudo nano /etc/pam.d/gdm-password
    If your system is Ubuntu 17.04 or older, run the following command: 
    sudo nano /etc/pam.d/lightdm
  3. Add the line below after the @include common-auth line
    auth       required   pam_u2f.so
manual-icon.svg Note:  If you have moved the u2f_keys file to /etc/Yubico/u2f_keys as mentioned in section 3, you will need to append authfile and a path to the PAM configuration, as shown below:
auth       required   pam_u2f.so authfile=/etc/Yubico/u2f_keys
  1. Press Ctrl+X and then Enter to save and close the file.

4.3 Configuring the system to require the YubiKey for TTY terminal 

  1. Open Terminal
  2. Run the following command: 
    sudo nano /etc/pam.d/login
  3. Add the line below after the “@include common-auth” line:
    auth       required   pam_u2f.so
manual-icon.svg Note:  If you have moved the u2f_keys file to /etc/Yubico/u2f_keys as mentioned in section 3, you will need to append authfile and a path to the PAM configuration, as shown below:
auth       required   pam_u2f.so authfile=/etc/Yubico/u2f_keys
  1. Press Ctrl+X and then Enter to save and close the file

You will no longer be able to log in to the computer without the YubiKey.

 

5 Troubleshooting

5.1 Enabling debug mode

If you are unable to login and are unsure why, you can enable debugging on the Yubico PAM-U2F module using the steps below. This provides insight into why the module is not allowing the login.

  1. Open Terminal
  2. Run the following command:
    sudo touch /var/log/pam_u2f.log
  3. If your system is Ubuntu 17.10 or newer, run the following command: 
    sudo nano /etc/pam.d/gdm-password
    If your system is Ubuntu 17.04 or older, run the following command: 
    sudo nano /etc/pam.d/lightdm
  4. Add debug debug_file=/var/log/pam_u2f.log to the end of the line that contains pam_u2f.so

Each subsequent login event will have the debug log saved in the /var/log/pam_u2f.log file.