YubiKey¶

We use YubiKeys as hardware security keys. They provide a phishing-resistant second factor, and SSH credential that never leaves the device.

PIN¶

Most features require user verification, i.e. a FIDO2 PIN. When registering the YubiKey on our SSO, the browser should prompt you to set a PIN.

Hint

If the browser doesn’t show a pop-up to set a PIN, use ykman or Yubico Authenticator to set one.

Warning

After 8 wrong entries, the FIDO2 application locks, and a reset is required, which wipes all keys on the device. Don’t guess your PIN.

ykman¶

If you prefer a CLI, use the YubiKey Manager CLI (ykman):

ykman fido access change-pin

Hint

You can install ykman via Homebrew:

brew install ykman

Yubico Authenticator¶

If you prefer a GUI, use the Yubico Authenticator GUI app (it replaced the old YubiKey Manager app):

Install, and open it, then plug in the YubiKey.
Open the Passkeys (FIDO2) section.
Choose Set PIN, and pick a PIN of 6–63 characters.

SSO / 2FA¶

When logging in to our SSO (Keycloak) the first time, it requires you to register the YubiKey as hardware key.

SSH authentication¶

Modern YubiKeys support FIDO2, so we bind the SSH key to the hardware. The private key stays on the YubiKey, and every login needs a physical touch.

Plug in the YubiKey, and create a non-resident FIDO2 SSH key:

ssh-keygen -t ed25519-sk -C {username}

Note

Add the generated ~/.ssh/id_ed25519_sk.pub to the servers, the same way as any SSH key.

Connect as usual, just touch the YubiKey when it blinks.

Hint

The built-in OpenSSH in macOS doesn’t support FIDO2 SSH keys. To make it work, it’s best to install openssh via Homebrew:

brew install openssh libfido2

Then use the switch-ssh-agent script to switch to the Homebrew OpenSSH daemon:

# Download switch-ssh-agent script.
sudo curl -sS -o /usr/local/bin/switch-ssh-agent https://handbook.confirm.ch/switch-ssh-agent

# Make it executable.
sudo chmod 755 /usr/local/bin/switch-ssh-agent

# Switch to the brew agent.
switch-ssh-agent brew

Make sure Homebrew’s bin/ comes first in your $PATH, so that ssh and friends resolve to the Homebrew versions (verify with which below):

which ssh
# /opt/homebrew/bin/ssh

which ssh-agent
# /opt/homebrew/bin/ssh-agent

which ssh-add
# /opt/homebrew/bin/ssh-add