SSH Login with Yubikey on MacOS Tahoe +

gistfile1.md

🔐 YubiKey SSH (FIDO2) Setup on macOS (Team Runbook)

This guide sets up hardware-backed SSH keys using a YubiKey.
Your private key stays inside the YubiKey. You share only the public key with sysadmins.

---

0. Prerequisites

Install Homebrew (if not already installed)

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

---

1. Install Required Packages

brew install yubikey-manager libfido2 openssh

Verify YubiKey is detected:

ykman list

You should see your YubiKey listed.

---

2. Force macOS to Use Homebrew OpenSSH (Important)

macOS ships OpenSSH without full FIDO2 support. We must use Homebrew’s OpenSSH.

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zprofile
source ~/.zshrc
source ~/.zprofile

Verify:

which ssh
which ssh-keygen

Expected:

/opt/homebrew/bin/ssh
/opt/homebrew/bin/ssh-keygen

---

3. Configure SSH to Use libfido2

nano ~/.ssh/config

Add:

Host *
  SecurityKeyProvider /opt/homebrew/opt/libfido2/lib/libfido2.dylib

Verify OpenSSH sees the provider:

ssh -Q security-key-providers

Expected output:

/opt/homebrew/opt/libfido2/lib/libfido2.dylib

---

4. Generate YubiKey-Backed SSH Key

Unplug and re-insert your YubiKey, then:

ssh-keygen -t ed25519-sk -O verify-required -C "your.email@noaa.gov" -f ~/.ssh/id_ed25519_yubikey

When prompted:

• Touch the YubiKey
• Set a PIN (recommended)
• Optional passphrase

This creates:

~/.ssh/id_ed25519_yubikey
~/.ssh/id_ed25519_yubikey.pub

---

5. Load the Key and Verify

ssh-add ~/.ssh/id_ed25519_yubikey
ssh-add -L

You should see:

sk-ssh-ed25519@openssh.com AAAA...

---

6. Share Public Key with Sysadmin

cat ~/.ssh/id_ed25519_yubikey.pub

Send that line to your sysadmin to add to:

~/.ssh/authorized_keys

---

7. (Optional) Lock SSH to This Key for a Host

nano ~/.ssh/config

Add:

Host myserver
  HostName myserver.company.com
  User youruser
  IdentityFile ~/.ssh/id_ed25519_yubikey
  IdentitiesOnly yes

Now:

ssh myserver

Touch YubiKey when prompted.

---

8. Recommended Hardening

Enforce touch for every login

ssh-keygen -t ed25519-sk -O verify-required -C "your.email@company.com" -f ~/.ssh/id_ed25519_yubikey

Set / Change YubiKey PIN

ykman fido access change-pin

---

9. Backup Key (Strongly Recommended)

Register a second YubiKey:

ssh-keygen -t ed25519-sk -C "your.email@company.com-backup" -f ~/.ssh/id_ed25519_yubikey_backup

Send both .pub keys to sysadmin.

---

10. Troubleshooting

Symptom	Fix
Unsupported query "security-key-providers"	You’re using Apple OpenSSH. Fix PATH to Homebrew OpenSSH
No FIDO SecurityKeyProvider specified	libfido2 not installed or wrong path in config
No touch prompt	Wrong key selected. Use IdentitiesOnly yes
Permission denied	Public key not in authorized_keys
YubiKey not detected	Run ykman list

---

11. Verification Checklist

which ssh
ssh -V
ssh -Q security-key-providers
ykman list

---

Security Model

• Private key never leaves YubiKey
• Physical presence required
• Phishing-resistant
• No SSH agent forwarding risk
• Works with standard OpenSSH servers