Linux Login with Yubikey

Posted on 1 2026

PAM, Pluggable Authentication Modules, is the system Linux uses to handle authentication for logins, sudo, screen unlock, and most other local authentication events. By adding a Yubikey to the PAM configuration, you require physical presence of the key in addition to a password for any of these operations. An attacker with your password but not your Yubikey cannot log in, unlock the screen, or escalate privileges.

This page uses pam-u2f, the U2F/FIDO2 PAM module from Yubico. It is the modern, maintained approach and works with all Yubikey 5 series devices without consuming a Yubikey slot.

A critical warning before you start

Misconfigured PAM files can lock you out of your own system entirely, including root access. This is not a theoretical risk. It happens.

Before editing any PAM file, open a terminal and keep it open for the entire procedure. Do not close it until you have tested the new configuration and confirmed it works. If something goes wrong, you can use the open terminal to revert the changes without needing to boot from a live USB.

Read the entire page before making any changes.

Install the Yubico PPA and packages

The libpam-u2f package in the standard Ubuntu repositories may lag behind the current release. Use the Yubico PPA for the latest version:

sudo add-apt-repository ppa:yubico/stable
sudo apt update
sudo apt install libpam-u2f pamu2fcfg

Register your Yubikey

Create the directory for the key mapping file:

mkdir -p /etc/Yubico

Insert your Yubikey and register it. When the key starts blinking, touch it:

pamu2fcfg -u${USER} | sudo tee /etc/Yubico/u2f_keys

The file /etc/Yubico/u2f_keys now contains the key handle and public key for your Yubikey, associated with your username. Storing it in /etc/Yubico/ rather than ~/.config/Yubico/ is important: if your home directory is encrypted, PAM cannot read it before the filesystem is unlocked, which causes lockouts.

Set the correct permissions:

sudo chmod 600 /etc/Yubico/u2f_keys
sudo chown root:root /etc/Yubico/u2f_keys

Register the backup Yubikey

Remove the primary key and insert the backup. Append its registration to the same line in the mapping file rather than creating a new line:

pamu2fcfg -n | sudo tee -a /etc/Yubico/u2f_keys

The -n flag appends to the existing entry rather than creating a new one. Both keys will now be associated with your username on the same line, separated by a colon.

Verify the file looks correct:

sudo cat /etc/Yubico/u2f_keys

It should show a single line for your username with both key handles separated by colons.

Create a PAM u2f module file

Create a dedicated PAM file for U2F to keep the configuration in one place:

echo "auth required pam_u2f.so authfile=/etc/Yubico/u2f_keys cue" | \
    sudo tee /etc/pam.d/u2f

The cue option causes PAM to print a message prompting you to touch the key. Without it, the system appears to hang silently waiting for the key, which is confusing.

If you want to use sufficient rather than required, the Yubikey alone unlocks without a password. required means both password and Yubikey are needed. For most setups, required is the correct choice.

Test with sudo first

Always test PAM changes with sudo before applying them to login. If sudo breaks, you can still revert using the open terminal from your current session.

Open /etc/pam.d/sudo and add the u2f include after the @include common-auth line:

@include common-auth
@include u2f

Save the file, then open a new terminal and test:

sudo echo test

Enter your password when prompted. The Yubikey should start blinking. Touch it. If test appears in the output, the configuration is working correctly.

If sudo fails or hangs, revert /etc/pam.d/sudo using the terminal you kept open.

Apply to desktop login (SDDM)

On Kubuntu the display manager is SDDM, not GDM. The source material this series draws on references gdm-password, which is the GNOME equivalent and does not exist on Kubuntu. The correct file is /etc/pam.d/sddm.

Open /etc/pam.d/sddm and add the u2f include before the @include common-auth line:

@include u2f
@include common-auth

The u2f include must come before common-auth for the SDDM login screen.

Apply to screen unlock

The KDE screen locker uses a separate PAM file. Open /etc/pam.d/kde and add the u2f include:

@include u2f
@include common-auth

If the file does not exist, create it:

sudo cp /etc/pam.d/sddm /etc/pam.d/kde

Then add the u2f include as above.

Apply to polkit

Polkit handles privilege escalation for graphical applications, the equivalent of sudo for GUI operations. Open /etc/pam.d/polkit-1 and add the u2f include:

@include u2f
@include common-auth

Apply to TTY login

For console logins, open /etc/pam.d/login and add the u2f include:

@include u2f
@include common-auth

Testing the full configuration

Log out of the desktop session and log back in. The SDDM login screen should accept your password and then prompt you to touch the Yubikey. If it does not prompt for the key, the configuration has not taken effect. Use a TTY (Ctrl+Alt+F2) to check the PAM files and revert if needed.

Test the screen locker by locking the session (Super+L or via the application launcher). Unlocking should require both password and Yubikey touch.

Test sudo from a terminal:

sudo -k && sudo echo test

The -k flag clears the sudo timestamp to force re-authentication.

Debugging PAM failures

If the Yubikey prompt does not appear, add debug to the pam_u2f line in /etc/pam.d/u2f:

auth required pam_u2f.so authfile=/etc/Yubico/u2f_keys cue debug debug_file=/var/log/pam_u2f.log

Check the log after a failed authentication attempt:

sudo tail -f /var/log/pam_u2f.log

Common issues:

  • The mapping file is not readable by PAM (check permissions)
  • The mapping file is in ~/.config/Yubico/ which is on an encrypted home directory
  • The Yubikey USB ID has changed because FIDO2 mode was toggled in Yubikey Manager
  • No Yubikey is inserted (PAM waits and eventually times out)

Recovery if locked out

If you are locked out despite having a terminal open, revert the PAM changes from that terminal:

sudo nano /etc/pam.d/sudo
# Remove the @include u2f line, save

If you are fully locked out with no open terminal, boot from a Kubuntu live USB, mount your filesystem, and edit the PAM files from there to remove the u2f includes.

Never close all terminals during PAM configuration. Never. One open authenticated session is your safety net throughout this process.