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_u2fwork 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_u2fmodule, 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
sudofor a selected user,how to safely test the changes without logging out and how to restore access if something goes wrong.
Table of contents
How hardware key login works in Linux
Authentication model: password and touch
The target flow is simple and system-independent:
The user types the account password (something they know).
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 |
| GNOME, usually also screen unlock |
KDE graphical login |
| Plasma with the SDDM display manager |
Privilege escalation |
| common to all distributions |
Text console |
| good fallback path, best left untouched |
|
| optional |
SSH |
| also requires changes in |
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_keyshas to be regenerated,alternatively, you can explicitly set the same
originduring 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 |
|
|
|
Fedora |
|
| shared files managed by |
RHEL / AlmaLinux / Rocky |
|
| EPEL required; shared files managed by |
Arch Linux |
|
| the package also includes |
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 |
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
AlmaLinux 10 (EL10) with GNOME and GDM.
A YubiKey with FIDO2 support (e.g. the YubiKey 5 series).
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.The EPEL repository enabled, which provides the
pam-u2fandpamu2fcfgpackages:
sudo dnf install -y epel-release
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? |
|---|---|---|
| The | Yes |
| Key registration tool (separate package) | Yes |
| Smartcard / CCID support | Optional |
| PKCS#11 / smartcard stack | Optional |
Note on AlmaLinux 10: in EPEL,
pam-u2fandpamu2fcfgare two separate packages. Installingpam-u2falone does not provide thepamu2fcfgtool.The PC/SC and OpenSC packages are not needed for FIDO2 itself, because
pam_u2ftalks to the key over HID. They are useful if you also use the YubiKey's smartcard/PIV features. Thepcsc-toolspackage may be unavailable on EL10 and is not required.
# Check that the key is visible to the systemIf 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 withdpkg -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:
the FIDO2 PIN,
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 |
| password + key PIN + touch | higher-risk workstations |
Register a backup key. A lost or damaged single key combined with
requiredin PAM means losing the ability to log in graphically and to usesudo.
Verifying the u2f_keys file
The file must not be empty:
wc -c ~/.config/Yubico/u2f_keys
Line format (abbreviated):
usernameThe 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
Back up every file before changing it.
Registration first,
requiredsecond. Enable the key requirement only onceu2f_keysis non-empty.Keep a root session or a second console open for the entire duration of testing.
Limit the requirement to a specific user with
pam_succeed_if, so you don't lock out other accounts.Do not manually edit shared files managed by system tools. On AlmaLinux and Fedora,
system-authandpassword-authbelong toauthselect; on Debian/Ubuntu,common-authbelongs topam-auth-update. Your changes may be overwritten. Thegdm-passwordandsudofiles 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.0Don't copy blindly. The default
gdm-passworddiffers between distributions and releases (e.g. on AlmaLinux 10 it may not containpam_console.so, and on Ubuntu you will find@include common-authinstead ofpassword-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.0On 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 |
| Effective order of steps |
|---|---|---|
GDM | after | password → key touch |
sudo | before | key touch → password |
How the single-user condition works
When the user is
jkowalski,pam_succeed_ifsucceeds (success=ignore) andpam_u2fis executed.When the user is someone else,
default=1skips 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 credentialsOnly 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:
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.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
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 |
|---|---|
| On AlmaLinux/Fedora/Debian it is a separate package: |
The | Registration was not completed (no PIN, no touch, an error). Delete the empty file and run |
The key stopped working after a hostname change | Re-register: |
Key not visible |
|
|
|
Login rejected despite correct configuration | Check the logs: |
Changes in | They were overwritten by |
Lockout after enabling | Restore the PAM backup from a text console. Never enable |
Quick deployment checklist
pam_u2fandpamu2fcfginstalled (on AlmaLinux: from EPEL)Key visible in
lsusbFIDO2 PIN set on the key
Final hostname settled
~/.config/Yubico/u2f_keysnon-empty, permissions600Backup key registered
Backup of
/etc/pam.d/gdm-password(or your display manager's file) and/etc/pam.d/sudoDisplay manager PAM:
pam_succeed_if+pam_u2f.so cueafter password verificationsudo PAM:
pam_succeed_if+pam_u2f.so cuebefore the shared stackFallback path prepared (text console, second account)
Test:
sudo -k; sudo trueTest: 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.