Registration/SSH/SSH-FIDO2-Quick-Start

SSH with FIDO2 Security Keys - Quick Start Guide

This guide shows you how to secure your SSH keys with FIDO2 security hardware keys (Yubikey, Feitian, Token2, etc.) 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 FIDO2 security key (e.g., Yubikey 5 series or newer, Feitian, Token2, etc.)
• OpenSSH 8.2 or newer
• For PIN setup: Either Chrome/Chromium/Brave browser OR yubikey-manager command-line tool (Yubikey only)
• For SSH key generation: openssh-client package

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 FIDO2 Security Key

What is a FIDO2 PIN? The PIN protects your security key's FIDO2 functions. For Yubikeys, it's separate from any other PINs (like the PIV PIN). Choose a PIN you can remember or save it to a keystore - you have 8 attempts before needing to reset.

Important:

If you lose your FIDO2 PIN, the security key must be reset. All FIDO2 data will be lost, including SSH keys stored on the device. After reset, you must generate new SSH keys and re-register them.

Option A: Command Line Setup (Yubikey only)

For Yubikeys, set a PIN using the yubikey-manager tool:

ykman fido access change-pin

You'll be asked to enter a new PIN.

Forgot your PIN or need to reset? You can reset your FIDO2 PIN using ykman fido reset or use the "Reset your security key" option shown in the browser security key settings (see image in Option B below).

Option B: Browser Setup (Chrome/Chromium/Brave)

You can also set a FIDO2 PIN using Chrome, Chromium, or Brave browser. This method works for all FIDO2 security hardware keys (Yubikey, Feitian, Token2, etc.), not just Yubikeys. Alternative: For Yubikeys specifically, you can also use Yubico Authenticator.

1. Open Security Key Settings:

Enter the following in your browser's address bar:

• Chrome/Chromium/Brave: chrome://settings/securityKeys

Manage security keys - shows options for Create PIN, Sign-in data, Fingerprints, and Reset security key

Note: The "Reset your security key" option (shown with red warning icons in the image above) can be used if you forget your PIN. Warning: Reset will delete all FIDO2 data including SSH keys!

2. Create a PIN:

Click Create a PIN and follow the prompts:

Create PIN dialog

Enter new PIN

3. PIN Created Successfully:

Step 2: Create an SSH Key

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

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

Connect your FIDO2 security key and create a new SSH key. Optional: Choose a descriptive filename like id_ed25519_sk_bwunicluster or id_ed25519_sk_nemo2:

ssh-keygen -t ed25519-sk -f ~/.ssh/id_ed25519_sk_bwunicluster

When prompted:

• Enter PIN: First, you'll be asked to enter your FIDO2 PIN (the one you set in Step 1)
• Passphrase: Press Enter to skip - the key is protected by requiring physical security key presence
• Touch your security key: The key will blink or light up - touch it to confirm

Two files are created:

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

Want keys stored on the security key 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

That's it! You can connect immediately - no 2FA unlock needed.

Step 4: Connect with Your Security Key

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 security key will blink or light up 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 bwunicluster.scc.kit.edu
  HostName bwunicluster.scc.kit.edu
  User fr_user1234
  IdentityFile ~/.ssh/id_ed25519_sk_bwunicluster

Host nemo2 login.nemo.uni-freiburg.de
  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 Security Keys (Optional)

Having backup security keys adds convenience - you can switch between devices without reconfiguring.

Note: If you lose your security key, 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 security key: id_ed25519_sk_key1 2. Create another key on your second security key: id_ed25519_sk_key2 3. Register both public keys in bwIDM as Interactive Keys 4. Configure ~/.ssh/config with multiple identities:

Host bwunicluster.scc.kit.edu uc*.scc.kit.edu login*.nemo.uni-freiburg.de
  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 security key.

Troubleshooting

Common Issues:

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

• Command not found?
  • Install yubikey-manager (for Yubikey command-line setup only):
    • Debian/Ubuntu: sudo apt install yubikey-manager
    • Fedora/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 Step 1

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

Official Yubico Documentation:

• Securing SSH with FIDO2 - Technical deep dive