How to Set Up a YubiKey: 2FA and SSH

You tapped it once during checkout, it worked, and now the key is sitting on your desk with no obvious next step. Every generic guide either stops at "register it as a security key" for one browser account, or jumps straight into OpenSSH flags nobody explains. Here's the sequence that actually gets both done — browser 2FA and SSH — without locking yourself out along the way.

Before anything else: register the backup key

As covered in what a YubiKey actually is, a single key with no backup turns "I lost my key" into "I'm locked out of my own accounts." Do this first, on every account you plan to protect, before touching SSH: register both your primary and backup key in the same sitting, using the same "add a security key" flow twice.

Step 1: browser 2FA (GitHub and Google)

Both platforms use the same underlying flow, just in different menus.

GitHub: Settings → Password and authentication → Security keys → Register a new security key. Insert the key, tap it when prompted, and give it a name you'll recognize later (e.g. "primary" vs "backup"). Repeat for the second key.

Google: Google Account → Security → 2-Step Verification → Security keys → Add security key. Same tap-to-register flow. Google will ask you to also keep at least one other 2FA method (authenticator app or backup codes) active, which is worth doing regardless of what the prompt requires.

Two minutes per account, no software installed, and both accounts now reject phishing attempts the way explained in the FIDO2 origin-check mechanism. It's the same category of quick, high-impact fix as the router-level basics in our home network security guide — small setup effort, outsized reduction in what an attacker can actually do to you.

Step 2: FIDO2 SSH login (the part most guides skip)

This is where consumer-facing guides stop and SSH-focused guides assume you already know OpenSSH. Neither gets you all the way to a working setup on its own.

My own homelab admin login — the Proxmox host covered in the homelab beginner's guide — runs through exactly this sequence. First, set a PIN on the key itself, which SSH resident keys require:

ykman fido access change-pin

Then generate a FIDO2-backed SSH key pair. The -O resident flag stores the key material on the hardware itself (so it's portable across machines); -O verify-required forces the PIN check on every use, not just a touch:

ssh-keygen -t ed25519-sk -O resident -O verify-required -C "yubikey-primary"

This produces a standard id_ed25519_sk / id_ed25519_sk.pub pair, but the private key is a stub — the actual signing happens on the hardware. Copy the public key to the server's authorized_keys, or paste it into GitHub's SSH keys page, exactly as you would any other SSH public key:

ssh-copy-id -i ~/.ssh/id_ed25519_sk.pub user@your-server

From here on, SSH-ing to that server prompts for the key's PIN and a physical tap — no password, and nothing an attacker can phish or keylog, because the private key material never leaves the hardware.

Common setup mistakes

Mistake	Consequence	Fix
Skipping -O resident	Key only works from the machine that generated it	Regenerate with -O resident so the key is portable
No PIN set on the key	ssh-keygen -t ed25519-sk fails outright	Run ykman fido access change-pin first
Only one key registered	A lost or damaged key locks you out entirely	Register a backup key on every account before relying on SSH-only access
Closing the original session before testing	If the new key doesn't work, you have no way back in	Open a second terminal and confirm login before closing the first
Assuming NFC works for SSH the same as browser login	SSH resident keys need a physical touch/PIN at the terminal, not just an NFC tap	Keep the key plugged in via USB for SSH sessions rather than relying on NFC

Testing it actually works before you need it

Before closing the terminal session you're already logged into, open a second one and attempt to log in using the new key. If it works, you have a real fallback if the first session drops. If it doesn't, you can debug from the still-open first session instead of being locked out entirely — this single habit is what separates "smooth setup" from "emergency console access at 2am."

Frequently asked questions

How do I set up my YubiKey for the first time?

Start with browser 2FA on your most important accounts (email, GitHub, Google) using each service's "add a security key" option, and register a backup key at the same time. SSH setup is a separate, optional step covered above once the basics are working.

Can I use a YubiKey for SSH login?

Yes — OpenSSH 8.2 and newer supports FIDO2 keys natively via ssh-keygen -t ed25519-sk, no extra software required on Linux or macOS. Windows needs a recent OpenSSH build, which ships by default on current Windows versions.

What happens if I lose my YubiKey after setting up SSH with it?

If you registered a backup key and added its public key to the same servers and accounts, you switch to that one and revoke the lost key. Without a backup key already in place, you'll need physical console access or another recovery method to regain SSH access.

Do I need a PIN for my YubiKey?

For resident SSH keys with -O verify-required, yes — the PIN is required and ssh-keygen will fail without one set via ykman fido access change-pin. For basic browser 2FA, a PIN isn't required, just the physical tap.

Does GitHub support YubiKey for SSH?

Yes — GitHub accepts FIDO2 SSH public keys (the ed25519-sk format) the same way it accepts any other SSH public key, pasted into your account's SSH keys settings.