A password is still the weakest link in access to a workstation or a server with a graphical interface. It can be shoulder-surfed, phished, captured by a keylogger or simply reused from another service. Anyone who learns it gets full access to your session, and through sudo to the entire system. A hardware key such as a YubiKey adds a second factor that cannot be copied over the network: a physical object you have to carry with you and touch. Importantly, the mechanism is the same across virtually every Linux distribution. It is built on PAM (Pluggable Authentication Modules) and the pam_u2f module, so once you understand the configuration, it works the same way on Debian, Ubuntu, Fedora, Arch or the Red Hat family. Only package names and configuration file details differ. In this article I first explain how it works in a distribution-agnostic way, and then walk through a complete step-by-step deployment using AlmaLinux 10 as the example.

Why read this article?

  • You significantly raise your security level at low cost. One key, a few packages and two configuration files. No MFA server, no subscription, no cloud dependency.

  • The knowledge transfers between systems. PAM and pam_u2f work the same way in every popular distribution. After reading, you will be able to deploy the same solution on any Linux your team uses.

  • You protect the most valuable moment: sudo. Even if someone learns your password, they cannot escalate privileges without the physical key.

  • You avoid locking yourself out of your own system. A mistake in PAM configuration can cut off access to an account. I show the order of operations, backups and a recovery plan that keep you safe from that scenario.

  • You get a proven procedure for an enterprise-class system. The AlmaLinux 10 example covers the pitfalls that make older guides simply not work, and the checklist at the end lets you repeat the configuration on further machines.

What you will learn

  • how hardware key authentication works through PAM and the pam_u2f module, regardless of distribution,

  • how the deployment differs on Debian/Ubuntu, Fedora, Arch and RHEL-family systems,

  • why I chose AlmaLinux 10 as the example and which packages it requires,

  • how to register a primary and a backup key and configure PAM for GDM and sudo for a selected user,

  • how to safely test the changes without logging out and how to restore access if something goes wrong.

Table of contents

  1. How hardware key login works in Linux

  2. Deployment example: preparing AlmaLinux 10

  3. Registering a key for a user account

  4. PAM configuration for GDM and sudo

  5. Testing, recovery plan and common problems

  6. FAQ

How hardware key login works in Linux

Authentication model: password and touch

The target flow is simple and system-independent:

  1. The user types the account password (something they know).

  2. The user confirms the intent to log in by touching the button on the key (something they have).

The second step is handled by the pam_u2f PAM module, developed by Yubico as an open-source project. It talks to the key using the FIDO2/U2F standard, so it works not only with a YubiKey but with any key compliant with that standard. The private key never leaves the device, so it cannot be stolen from disk or intercepted on the network.

PAM as the common layer across all distributions

PAM is the layer that almost every authentication in Linux passes through. Each service (display manager, sudo, su, SSH, console) has its own file in /etc/pam.d/ describing the stack of modules to run. Adding pam_u2f to a given file means the key is required only for that service.

Access path

Typical PAM file

Notes

GNOME graphical login

/etc/pam.d/gdm-password

GNOME, usually also screen unlock

KDE graphical login

/etc/pam.d/sddm

Plasma with the SDDM display manager

Privilege escalation

/etc/pam.d/sudo

common to all distributions

Text console

/etc/pam.d/login

good fallback path, best left untouched

su

/etc/pam.d/su

optional

SSH

/etc/pam.d/sshd

also requires changes in sshd_config; -sk keys are better for SSH

In the example in this article we protect GDM and sudo. The text console remains unchanged and serves as the fallback path.

Binding the key to the hostname

This behaviour is the same in every distribution. The key is bound to the host. During registration (pamu2fcfg), a relying party identifier is stored in the form:

pam://

pam_u2f later uses it to verify the key's response. Consequences:

  • changing the hostname invalidates the existing binding, and the entry in ~/.config/Yubico/u2f_keys has to be regenerated,

  • alternatively, you can explicitly set the same origin during registration and in the PAM configuration, making it independent of the hostname.

Checking the hostname:

hostname
hostnamectl --static

Tip: settle on the final hostname before registering the key. It will save you a reconfiguration.

Differences between distributions

The principle is shared, but deployment details differ. The most important ones:

Family

Packages

Shared PAM files

What to watch out for

Debian / Ubuntu

libpam-u2f, pamu2fcfg

common-auth (included via @include)

common-auth is managed by pam-auth-update, so make changes in service-specific files

Fedora

pam-u2f, pamu2fcfg

system-auth, password-auth

shared files managed by authselect

RHEL / AlmaLinux / Rocky

pam-u2f, pamu2fcfg (from EPEL)

system-auth, password-auth

EPEL required; shared files managed by authselect

Arch Linux

pam-u2f

system-auth

the package also includes pamu2fcfg

Package names may change between releases. Check them in your distribution's repository before installing (apt search pam-u2f, dnf search pam-u2f, pacman -Ss pam-u2f).

Key registration, PAM rule syntax, the single-user condition, and the testing and recovery procedure are identical across all distributions. That is why the rest of the article, although shown on AlmaLinux 10, mostly carries over one-to-one.

Deployment example: preparing AlmaLinux 10

Why AlmaLinux 10

I chose AlmaLinux 10 as the example for several reasons:

Reason

What it means in practice

RHEL compatibility

AlmaLinux maintains binary (ABI) compatibility with Red Hat Enterprise Linux. A procedure verified here will also work on RHEL 10, Rocky Linux 10 and Oracle Linux 10. It therefore covers a large share of corporate servers and workstations

Long support cycle

Active support until May 2030, security updates until May 2035. A configuration deployed today will stay relevant for years

Free and independent

The distribution is free and community-governed by a non-profit foundation (AlmaLinux OS Foundation). No subscription required

Enterprise environment

The RHEL family is the typical choice where stability, auditability and compliance with security requirements matter, which is exactly where MFA makes the most sense

Most pitfalls

EL10 differs from EL8/EL9 in several details (a separate pamu2fcfg package, no pcsc-tools, a different default gdm-password). Popular guides are most often outdated here, so a detailed description adds the most value

If you use another distribution, substitute the package installation commands in the following steps and compare your PAM files with the differences table above.

Prerequisites

  1. AlmaLinux 10 (EL10) with GNOME and GDM.

  2. A YubiKey with FIDO2 support (e.g. the YubiKey 5 series).

  3. A FIDO2 PIN configured on the key. Without it, registration will usually fail. You can set the PIN e.g. in Yubico Authenticator or with ykman fido access change-pin.

  4. The EPEL repository enabled, which provides the pam-u2f and pamu2fcfg packages:

sudo dnf install -y epel-release
  1. The exact system username:

id -un

In the examples below I use the username jkowalski. Replace it with your own.

Installing packages

Package

Role

Required?

pam-u2f

The pam_u2f.so PAM module

Yes

pamu2fcfg

Key registration tool (separate package)

Yes

pcsc-lite, pcsc-lite-ccid

Smartcard / CCID support

Optional

opensc

PKCS#11 / smartcard stack

Optional

Note on AlmaLinux 10: in EPEL, pam-u2f and pamu2fcfg are two separate packages. Installing pam-u2f alone does not provide the pamu2fcfg tool.

The PC/SC and OpenSC packages are not needed for FIDO2 itself, because pam_u2f talks to the key over HID. They are useful if you also use the YubiKey's smartcard/PIV features. The pcsc-tools package may be unavailable on EL10 and is not required.

# Check that the key is visible to the system

If dnf stalls on a third-party repository (e.g. a GPG key problem), you can temporarily disable it:

sudo dnf --disablerepo=<repository_name> install -y pam-u2f pamu2fcfg

Debian/Ubuntu equivalent:

sudo apt install libpam-u2f pamu2fcfg

Verifying the installation

rpm -q pam-u2f pamu2fcfg

All three commands should return a result without errors. Only then move on.

On Debian/Ubuntu the module is usually located at /usr/lib/x86_64-linux-gnu/security/pam_u2f.so, and you can check the packages with dpkg -l | grep u2f.

Registering a key for a user account

This stage looks the same in every distribution.

Before you run pamu2fcfg

  • The key is plugged into a USB port.

  • A FIDO2 PIN is set on the key.

  • The hostname is final (or you knowingly accept re-registering later).

Registering the primary and backup keys

Run the commands as your own user, without sudo:

mkdir -p ~/.config/Yubico

After you run pamu2fcfg, the system will ask for:

  1. the FIDO2 PIN,

  2. a touch of the button on the key.

Optionally, you can require the PIN on every subsequent authentication as well. This is a stronger variant (password + PIN + touch), but more cumbersome day to day:

pamu2fcfg -N > ~/.config/Yubico/u2f_keys

Variant

What the user provides

When to choose it

Default

password + key touch

workstations, everyday work

-N (PIN)

password + key PIN + touch

higher-risk workstations

Register a backup key. A lost or damaged single key combined with required in PAM means losing the ability to log in graphically and to use sudo.

Verifying the u2f_keys file

The file must not be empty:

wc -c ~/.config/Yubico/u2f_keys

Line format (abbreviated):

username

The default path from which pam_u2f reads keys:

$HOME/.config/Yubico/u2f_keys

PAM configuration for GDM and sudo

The rule syntax is universal. Only the names of the shared files included at the end of the stack differ (password-auth / system-auth on AlmaLinux, common-auth on Debian/Ubuntu).

Safety rules before editing PAM

  1. Back up every file before changing it.

  2. Registration first, required second. Enable the key requirement only once u2f_keys is non-empty.

  3. Keep a root session or a second console open for the entire duration of testing.

  4. Limit the requirement to a specific user with pam_succeed_if, so you don't lock out other accounts.

  5. Do not manually edit shared files managed by system tools. On AlmaLinux and Fedora, system-auth and password-auth belong to authselect; on Debian/Ubuntu, common-auth belongs to pam-auth-update. Your changes may be overwritten. The gdm-password and sudo files are safe to edit.

Graphical login: gdm-password

sudo cp -a /etc/pam.d/gdm-password 

Add directly after the password-auth line, i.e. after password verification:

auth     [

A complete example file for AlmaLinux 10 with GNOME, based on the default gdm-password:

#%PAM-1.0

Don't copy blindly. The default gdm-password differs between distributions and releases (e.g. on AlmaLinux 10 it may not contain pam_console.so, and on Ubuntu you will find @include common-auth instead of password-auth). Make your changes in your current file, inserting the two lines right after the password verification step. Treat the listing above as a reference point.

The cue option displays a prompt asking the user to touch the key, so they know the system is waiting for them.

Privilege escalation: sudo

sudo cp -a /etc/pam.d/sudo 

Target content on AlmaLinux 10:

#%PAM-1.0

On Debian/Ubuntu, insert the same two lines before @include common-auth.

Order matters. pam_u2f sits before the shared stack is included, so the key confirmation comes first, followed by the standard password path.

Service

pam_u2f position

Effective order of steps

GDM

after password-auth

password → key touch

sudo

before system-auth

key touch → password

How the single-user condition works

  • When the user is jkowalski, pam_succeed_if succeeds (success=ignore) and pam_u2f is executed.

  • When the user is someone else, default=1 skips the next rule (i.e. pam_u2f), so the key is not required.

A typo in the username is a real risk. A wrong name means the condition will never apply to your account. Enter exactly the output of id -un.

If you want to apply the requirement to an entire admin group instead of one person, use a group condition, e.g. pam_succeed_if.so user ingroup wheel (on Debian/Ubuntu the admin group is usually sudo).

Testing, recovery plan and common problems

The testing and recovery procedure is the same for all distributions.

Testing without logging out

In an already open session, with a second root console in reserve:

# Invalidate cached sudo credentials

Only after a successful sudo test, log out and check the GDM login. Finally, lock the screen and check whether unlocking also requires the key.

Restoring access

If login or sudo stops working:

  1. Log in on a text console (Ctrl+Alt+F3) as root or another local user. This path uses /etc/pam.d/login, which we did not change.

  2. Restore the backups:

cp -a /etc/pam.d/gdm-password.bak.XXXXXXXXXXXXXX /etc/pam.d/gdm-password
cp -a /etc/pam.d/sudo.bak.XXXXXXXXXXXXXX /etc/pam.d/sudo
  1. Alternatively, temporarily comment out the lines containing pam_u2f.so.

On Ubuntu the root account is locked by default. Make sure beforehand that you have another fallback path, e.g. a second admin account or recovery mode.

Common problems

Symptom

Cause / solution

pamu2fcfg: command not found after installing pam-u2f

On AlmaLinux/Fedora/Debian it is a separate package: pamu2fcfg

The u2f_keys file is 0 B

Registration was not completed (no PIN, no touch, an error). Delete the empty file and run pamu2fcfg again

The key stopped working after a hostname change

Re-register: pamu2fcfg > ~/.config/Yubico/u2f_keys

Key not visible

lsusb | grep -i yubico, try another USB port, check another cable/adapter

dnf fails on a third-party repository / GPG

dnf --disablerepo=<repository_name> ... or fix the repository key

Login rejected despite correct configuration

Check the logs: journalctl -b | grep -i pam_u2f, and on SELinux systems also sudo ausearch -m avc -ts recent

Changes in system-auth / common-auth disappeared

They were overwritten by authselect or pam-auth-update. Edit service-specific files

Lockout after enabling required without a registered key

Restore the PAM backup from a text console. Never enable required before u2f_keys is non-empty

Quick deployment checklist

  • pam_u2f and pamu2fcfg installed (on AlmaLinux: from EPEL)

  • Key visible in lsusb

  • FIDO2 PIN set on the key

  • Final hostname settled

  • ~/.config/Yubico/u2f_keys non-empty, permissions 600

  • Backup key registered

  • Backup of /etc/pam.d/gdm-password (or your display manager's file) and /etc/pam.d/sudo

  • Display manager PAM: pam_succeed_if + pam_u2f.so cue after password verification

  • sudo PAM: pam_succeed_if + pam_u2f.so cue before the shared stack

  • Fallback path prepared (text console, second account)

  • Test: sudo -k; sudo true

  • Test: log out and log back in graphically

  • Test: lock and unlock the screen

FAQ

Will this configuration work on Ubuntu, Debian or Fedora?

Yes. The mechanism is identical, because all these systems use PAM and the pam_u2f module. Only the package names (e.g. libpam-u2f on Debian/Ubuntu) and the names of the shared PAM files (common-auth instead of system-auth) change. Key registration and the rules in gdm-password and sudo are the same.

Do I need a YubiKey specifically?

No. pam_u2f works with any FIDO2/U2F-compliant key, e.g. Nitrokey, SoloKeys or Google Titan. YubiKey is simply the most popular and well documented.

Why is the example shown on AlmaLinux 10 and not on Ubuntu?

Because AlmaLinux is binary-compatible with RHEL, so the same procedure covers RHEL, Rocky and Oracle Linux, i.e. a large share of corporate environments. It also has security support until 2035, and EL10 has the most differences compared to older guides, so a detailed description is most needed there.

How does the AlmaLinux 10 configuration differ from instructions for EL8 and EL9?

On AlmaLinux 10, pamu2fcfg is a separate EPEL package, pcsc-tools is not needed (and may be unavailable), and the default gdm-password may differ from older releases. That is why the configuration should always be applied to the current file on the system, not to a copied older listing.

Will the key also protect SSH login?

No. The configuration described here covers only graphical login and sudo. SSH uses /etc/pam.d/sshd and its own authentication mechanisms. For SSH it is better to use ed25519-sk keys stored on the hardware key, which is a topic for a separate article.

What happens if I lose my key?

If you registered a backup key, you simply use it and remove the lost key's entry from u2f_keys. If not, you log in through a text console and restore the PAM backup or comment out the pam_u2f.so lines. That is why registering a second key should be a mandatory step.

Can I store the keys centrally instead of in the home directory?

Yes. pam_u2f supports the authfile= option, e.g. authfile=/etc/u2f_mappings, where the administrator maintains mappings for all users. This is more convenient with many accounts and gives the administrator control over which keys are allowed, because users cannot change the file themselves.