Registration/SSH/SSH-FIDO2-Quick-Start

SSH with Yubikey - Quick Start Guide

This guide shows you how to secure your SSH keys with a Yubikey using FIDO2.

Why FIDO2 SSH Keys? FIDO2 SSH keys (ED25519-SK) offer significant advantages: No 2-factor unlock required - work immediately after registration Hardware-protected - private key never leaves the Yubikey Physical presence required - you must touch the key to authenticate Note: ECDSA-SK keys are not supported on these clusters. Use ED25519-SK instead. Cluster Support Cluster FIDO2 Support bwUniCluster 3.0 ✓ bwForCluster BinAC 2 ✗ bwForCluster Helix ✗ bwForCluster JUSTUS 2 ✗ bwForCluster NEMO 2 ✓

Requirements

• A Yubikey (5 series or newer)
• OpenSSH 8.2 or newer
• Linux system with yubikey-manager and openssh-client packages

Check your OpenSSH version:

ssh -V
ssh -Q PubkeyAcceptedAlgorithms | grep sk-ssh-ed25519@openssh.com

Need help with installation? See the detailed setup guide for your operating system.

Quick Start Guide

Step 1: Set up your Yubikey

What is a FIDO2 PIN? The PIN protects your Yubikey's FIDO2 functions. It's separate from any other PINs on your Yubikey (like the PIV PIN).

Set a PIN for your Yubikey's FIDO2 functionality:

ykman fido access change-pin

You'll be asked to enter a new PIN. Choose a PIN you can remember - you have 8 attempts before needing to reset.

Note: For GUI setup, you can use Yubico Authenticator instead.

Forgot your PIN or need to reset? See the troubleshooting guide.

Step 2: Create an SSH Key

What happens here? This creates a non-discoverable FIDO2 SSH key. The private key material is wrapped/encrypted with a secret stored on your Yubikey - the Yubikey is required for every authentication, but the actual key credentials are stored on your computer.

Note: For keys stored directly on the Yubikey (resident/discoverable keys), see the resident keys documentation.

Connect your Yubikey and create a new SSH key:

ssh-keygen -t ed25519-sk

When prompted:

• Enter PIN: First, you'll be asked to enter your FIDO2 PIN (the one you set in Step 1)
• Filename: Choose a descriptive name like id_ed25519_sk_bwunicluster or id_ed25519_sk_nemo2
• Passphrase: Press Enter to skip - the key is protected by requiring physical Yubikey presence
• Touch your Yubikey: The key will blink - touch it to confirm

Two files are created:

• ~/.ssh/id_ed25519_sk_bwunicluster - key handle (encrypted credentials that require the Yubikey)
• ~/.ssh/id_ed25519_sk_bwunicluster.pub - public key (this is what you'll upload)

Want keys stored on the Yubikey itself? See resident keys documentation for discoverable keys that can be copied to any machine.

Step 3: Register Your Public Key

FIDO2 SSH Keys work immediately without 2-factor authentication! Unlike regular SSH keys, FIDO2 keys do not need to be "unlocked" with username/password. They work as soon as you register them as Interactive Keys.

For bwUniCluster 3.0 and bwForCluster NEMO 2:

1. View your public key:

cat ~/.ssh/id_ed25519_sk_bwunicluster.pub

2. Copy the complete output (starts with sk-ssh-ed25519@openssh.com)

3. Follow the SSH Key Registration Guide to:

• Add your public key in bwIDM/bwServices
• Register it as an Interactive Key for your cluster
• Connect immediately - no 2FA unlock needed!

Step 4: Connect with Your Yubikey

After registering your key as an Interactive Key in bwIDM:

ssh -i ~/.ssh/id_ed25519_sk_bwunicluster your_username@bwunicluster.scc.kit.edu

What to expect: 1. Your Yubikey will blink 2. Touch it to authenticate 3. You're logged in - no password needed!

Tip: Add your key to ~/.ssh/config to avoid typing the -i option every time:

Host bwuni
  HostName bwunicluster.scc.kit.edu
  User fr_user1234
  IdentityFile ~/.ssh/id_ed25519_sk_bwunicluster

Host nemo2
  HostName login.nemo.uni-freiburg.de
  User fr_user1234
  IdentityFile ~/.ssh/id_ed25519_sk_nemo2

Then simply connect with: ssh bwuni or ssh nemo2

See SSH config examples for more advanced configurations.

Advanced Topics

Using Multiple Yubikeys (Optional) ==

Why? Having backup Yubikeys adds convenience - you can switch between devices without reconfiguring.

Note: If you lose your Yubikey, you can still access the cluster using regular SSH keys (with 2FA unlock) or password login with TOTP.

Setup:

1. Create a key on your first Yubikey: id_ed25519_sk_key1 2. Create another key on your second Yubikey: id_ed25519_sk_key2 3. Register both public keys in bwIDM as Interactive Keys 4. Configure ~/.ssh/config with multiple identities:

Host bwuni nemo2
  User fr_user1234
  IdentityFile ~/.ssh/id_ed25519_sk_key1
  IdentityFile ~/.ssh/id_ed25519_sk_key2

SSH will automatically try each key until it finds one with a connected Yubikey.

Troubleshooting

Common Issues:

• Key not working?
  • Make sure your Yubikey is plugged in
  • Try unplugging and re-plugging the Yubikey
  • Check if the key is blinking (requires touch)

• Command not found?
  • Install yubikey-manager:
    • Debian/Ubuntu: sudo apt install yubikey-manager
    • RHEL/Rocky/Alma: sudo dnf install yubikey-manager
  • Install openssh-client if missing

• Old OpenSSH?
  • Check version: ssh -V
  • Update to version 8.2 or newer
  • On older systems, consider using a newer OpenSSH version or upgrade your OS

• "invalid format" or "unknown key type"?
  • Your OpenSSH version is too old (needs 8.2+)
  • The cluster doesn't support FIDO2 keys (only bwUniCluster 3.0 and NEMO 2)

• PIN locked after too many attempts?
  • Reset FIDO2 PIN: See PIN reset guide

Need more help? See the complete troubleshooting guide.

Learn More

Cluster-Specific Documentation:

• Complete SSH Key Registration Guide for bwUniCluster/bwForCluster

Yubikey & FIDO2 SSH Documentation:

• Comprehensive Yubikey Guide - Setup, configuration, troubleshooting
  • Resident Keys - Store keys directly on Yubikey
  • SSH Config Examples - Automate your SSH connections
  • Backup Strategies - Multi-key and recovery setups

Official Yubico Documentation:

• Securing SSH with FIDO2 - Technical deep dive