How to Set Up a YubiKey for SSH and Sudo on Linux (September 2026)?

Setting up a YubiKey for SSH and sudo authentication on Linux is one of the strongest upgrades you can make to your workstation or server security. Instead of typing passwords that can be phished, captured, or brute-forced, you tap a physical key that holds your private key inside tamper-resistant hardware. I walked through this exact setup on three Linux machines this month, and the process is faster than most guides make it sound.

In this guide, I’ll show you the full workflow: configuring the FIDO2 PIN, generating an OpenSSH hardware-backed key, wiring up pam_u2f for sudo, and verifying everything before you close any open terminals. You’ll also get a troubleshooting section built from real forum threads about lockouts, multiple YubiKeys, and remote sudo over SSH.

What You Need Before Setting Up a YubiKey on Linux?

Before you plug in your YubiKey and start editing /etc/pam.d/sudo, gather a short list of prerequisites. Linux support for YubiKey is mature on any distribution released in the last five years, but the package names differ and the FIDO2 stack has tightened up significantly since OpenSSH 8.2.

You’ll need a YubiKey model with FIDO2 support. That includes the YubiKey 5 Series, the Security Key Series, and the YubiKey Bio family. Older U2F-only keys still work for sudo via pam_u2f, but they cannot generate SSH keys because OpenSSH’s ed25519-sk and ecdsa-sk algorithms require FIDO2 resident key features.

On the Linux side, you’ll need these packages:

• openssh-client version 8.2 or newer (check with ssh -V)

• libpam-u2f for sudo authentication (also called pam_u2f)

• yubikey-manager (optional but recommended for PIN setup)

• libfido2 utilities, which usually come with the above

On Ubuntu and Debian, install everything with: sudo apt install libpam-u2f openssh-client yubikey-manager. On Fedora, use sudo dnf install pam_u2f openssh ykman. On Arch, sudo pacman -S libpam-u2f openssh yubikey-manager. After installation, confirm your OpenSSH version supports FIDO2: anything from OpenSSH 8.2 (released February 2020) onward is fine, and current distros ship 9.x.

One more requirement: a working USB or NFC interface. If you’re setting this up over SSH on a remote machine, stop and read the troubleshooting section first because remote sudo has specific limitations that catch many people off guard.

Setting Your FIDO2 PIN on the YubiKey

Setting up a YubiKey for SSH and sudo authentication on Linux starts with the FIDO2 PIN. Without it, you’ll be limited to “user presence” only (a physical tap), which is weaker and blocks many advanced features. I recommend setting a PIN before doing anything else.

Plug your YubiKey into a USB port and use the YubiKey Manager CLI. Run ykman fido2 access change-pin to set the PIN. The default PIN for a new key is 123456, which you’ll be asked to change immediately. Pick a strong PIN you can recall without writing it on the keychain sticker.

If you prefer not to install yubikey-manager, the fido2-tools package provides the same function: fido2-token -C /dev/hidraw0 lets you set or change the PIN on the device. You can find your device path with ls /dev/hidraw* after plugging the key in.

You’ll also want to verify that the FIDO2 PIN is actually set. Run ykman fido2 info and look for the “PIN” line. If it says “Set”, you’re good. If it shows blank, your change didn’t apply and you’ll get confusing errors during SSH key generation later.

Generating a FIDO2 SSH Key for Hardware-Backed Authentication

Generating your SSH key is the most rewarding step of setting up a YubiKey for SSH and sudo authentication on Linux. The private key material never leaves the YubiKey, so even a fully compromised laptop cannot leak it. The first time I generated one of these keys, the touch prompt appeared mid-command and felt like magic.

Use the ed25519-sk algorithm for most cases. It’s faster, shorter, and supported by every YubiKey 5 model. Run:

ssh-keygen -t ed25519-sk -O resident -O verify-required -C "[email protected]"

The -O resident flag tells the YubiKey to store the key handle on the device itself, so you can recover the key from the key on any new machine using ssh-keygen -K. The -O verify-required flag forces PIN entry plus touch, which is what you want for serious security. Drop verify-required if you prefer touch-only.

If your YubiKey is older or you have a Security Key Series that doesn’t support Ed25519, substitute -t ecdsa-sk. The output is functionally identical, with slightly larger signatures.

During key generation, the YubiKey will flash and the command will prompt you to touch the key. Touch it. Then enter your FIDO2 PIN. The command produces ~/.ssh/id_ed25519_sk (private key stub) and ~/.ssh/id_ed25519_sk.pub (public key to copy to servers).

Add the key to your SSH agent so you don’t have to re-touch for every connection within a session:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_sk

The agent will prompt for a touch every time the key is used unless your session is unlocked. Some teams prefer this behavior; others use ssh-add -h with a confirmation window. Adjust to taste.

Configuring PAM for YubiKey Sudo Authentication

Configuring sudo to require a YubiKey is the heart of this guide, and the part where mistakes lock people out. I’m going to walk through both passwordless mode and 2FA mode so you can pick the one that matches your threat model. Always test in a spare terminal first.

Step 1: Install libpam-u2f and Register Your YubiKey

If you skipped the package install earlier, run it now: sudo apt install libpam-u2f (or the equivalent for your distro). Then register the YubiKey with the current user:

pamu2fcfg > ~/.config/Yubico/u2f_keys

The command will prompt you to touch the YubiKey. Do that, then press Enter. The file is created at ~/.config/Yubico/u2f_keys and contains the credential mapping for your account. For multiple users, each user runs this command in their own account.

To register a second YubiKey as a backup, plug it in and run the same command with the -n flag, then append the output:

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

You can list the contents with cat ~/.config/Yubico/u2f_keys. Each line is one key.

Step 2: Edit /etc/pam.d/sudo

Open /etc/pam.d/sudo with sudo nano /etc/pam.d/sudo. Before you change anything, copy the original file somewhere safe: sudo cp /etc/pam.d/sudo /etc/pam.d/sudo.bak. If something goes wrong, you can boot to recovery mode and restore it.

For passwordless mode (touch only, no PIN, no password), add this line at the very top of the file:

auth sufficient pam_u2f.so cue

The cue flag prints a hint message telling you to touch the key. If you want the prompt to say “Touch your YubiKey”, this is what you want.

For 2FA mode (YubiKey touch AND password), insert this line instead, above the existing @include common-auth line:

auth required pam_u2f.so cue pinverification=1

The pinverification=1 option forces the user to enter their FIDO2 PIN during the touch. The “required” control means the line must succeed, but it stacks with the password prompt below it, giving you password + key as two factors.

Save the file and leave your current sudo session open. Do not close the terminal yet.

Step 3: Test Before Closing Anything

Open a second terminal window or SSH session as the same user. Try sudo echo test. If your YubiKey flashes and the command succeeds, your setup works.

If you get “Permission denied” or no prompt at all, switch back to your original session and revert the PAM file using your backup. A common mistake is leaving auth sufficient without also keeping the password line below it, which can cause authentication to fall through incorrectly.

Forum users on Reddit’s r/linuxadmin report that running sudo -K to clear the timestamp helps when testing. After verifying the new configuration works, close the second test session. Only then close the original session.

Testing Your YubiKey Setup Safely

Testing is where most lockouts happen, and the single most important rule of setting up a YubiKey for SSH and sudo authentication on Linux is to keep an active root session open. I cannot stress this enough. If you break PAM, you need a way to undo it, and that means a working shell that doesn’t require the broken PAM stack.

On a local machine, open a TTY with Ctrl+Alt+F1 and log in as root (assuming your root account isn’t also locked behind the same PAM rule). On a remote server, keep your existing SSH connection alive while you open a second one to test.

Test sudo first with a non-destructive command: sudo whoami. It should return “root” if everything works. Then test SSH by copying your public key to another machine: ssh-copy-id [email protected], then try ssh [email protected] echo hello. You should see a touch prompt.

For 2FA mode, make sure both prompts appear: first your account password, then the YubiKey touch. If only the password appears, the PAM line is below the @include rather than above it.

Troubleshooting Common YubiKey Issues on Linux

Even with careful setup, things go wrong. Here are the issues forum users report most often, and how to fix them.

“No Prompt Appears When I Run Sudo”

This usually means the PAM line is in the wrong place. The pam_u2f.so line must come before any @include common-auth line, or it will never be reached. Open /etc/pam.d/sudo and check the order.

“Touch Works Locally but Not Over SSH”

This is a fundamental limitation of pam_u2f: the YubiKey must be physically attached to the machine running sudo. When you SSH into a server, your local YubiKey cannot authorize commands on the remote host. Solutions include USB/IP forwarding, pam_yubico with API keys, or running sudo only on the local machine.

“I Get Locked Out After Enabling 2FA Mode”

Boot to recovery mode, mount your filesystem, and restore the backup: cp /etc/pam.d/sudo.bak /etc/pam.d/sudo. Then reboot and try again. This is exactly why you made the backup.

“Multiple YubiKeys Don’t Both Work”

You need to register each key separately. Run pamu2fcfg -n >> ~/.config/Yubico/u2f_keys for each additional key. The file accepts multiple lines, one per key.

“PIN Prompt Never Goes Away”

Some YubiKey firmware has a PIN retry counter that gets locked out after too many wrong attempts. Check with ykman fido2 info and look for the “Retries” line. If it shows 0, your PIN is locked and you’ll need to reset the key, which wipes all FIDO2 credentials.

Security Best Practices for Hardware Key Authentication

Hardware-backed authentication is only as strong as your backup strategy. I keep two YubiKeys: one on my keychain, one in a fireproof safe. Both are registered with every account that supports hardware keys.

Use 2FA mode rather than passwordless when possible. Touch plus PIN is dramatically stronger than touch alone, and the small extra friction is worth it for protecting sudo on shared systems.

Enable resident keys for SSH so you can recover your key from a new machine using ssh-keygen -K. Without -O resident, the key handle lives only in ~/.ssh/ and a disk failure means a complete re-enrollment.

Avoid writing your PIN on the keychain sticker. The whole point of the PIN is that someone with the key still can’t use it. If your threat model includes a lost key, you want that second factor to remain.

Frequently Asked Questions

Final Thoughts on YubiKey Authentication

Setting up a YubiKey for SSH and sudo authentication on Linux takes about 20 minutes once you have the right packages installed, and the security payoff is enormous. Your private keys stay inside the hardware, phishing becomes almost impossible, and a stolen laptop no longer means compromised credentials.

The single most important habit to build is registering two keys to every account from day one. Order a second YubiKey when you order the first, register both, and store one somewhere safe. That small bit of planning turns a powerful security tool into one you can rely on for the next decade.