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
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 resident FIDO2 SSH key:
ssh-keygen -t ed25519-sk -O resident -O verify-required -O application=ssh:confirm -C {username}
Important
On a second machine, don’t regenerate the key. Load the resident key from the YubiKey instead:
ssh-keygen -K
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.