Latest revision as of 17:38, 3 December 2025

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).

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. Choose a PIN you can remember - you have 8 attempts before needing to reset.

Forgot your PIN or need to reset? You can reset your FIDO2 PIN using the same browser interface. See the troubleshooting guide 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.

1. Open Security Key Settings:

Enter the following in your browser's address bar:

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

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:

3. PIN Created Successfully:

Alternative: For Yubikeys specifically, you can also use Yubico Authenticator.

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 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:

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 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
  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 Security Keys (Optional)

Why? 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 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 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
  - 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

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

Registration/SSH/SSH-FIDO2-Quick-Start: Difference between revisions

Latest revision as of 17:38, 3 December 2025

Contents

SSH with FIDO2 Security Keys - Quick Start Guide

Requirements

Quick Start Guide

Step 1: Set up your FIDO2 Security Key

Option A: Command Line Setup (Yubikey only)

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

Step 2: Create an SSH Key

Step 3: Register Your Public Key

Step 4: Connect with Your Security Key

Advanced Topics

Using Multiple Security Keys (Optional)

Troubleshooting

Learn More

Requirements

Quick Start Guide

Step 1: Set up your Yubikey

Step 2: Create an SSH Key

Step 3: Register Your Public Key

Step 4: Connect with Your Yubikey

Advanced Topics

Using Multiple Yubikeys (Optional)

Troubleshooting

Learn More

Navigation menu

Registration/SSH/SSH-FIDO2-Quick-Start: Difference between revisions

Latest revision as of 17:38, 3 December 2025

SSH with FIDO2 Security Keys - Quick Start Guide

Requirements

Quick Start Guide

Step 1: Set up your FIDO2 Security Key

Option A: Command Line Setup (Yubikey only)

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

Step 2: Create an SSH Key

Step 3: Register Your Public Key

Step 4: Connect with Your Security Key

Advanced Topics

Using Multiple Security Keys (Optional)

Troubleshooting

Learn More

Requirements

Quick Start Guide

Step 1: Set up your Yubikey

Step 2: Create an SSH Key

Step 3: Register Your Public Key

Step 4: Connect with Your Yubikey

Advanced Topics

Using Multiple Yubikeys (Optional)

Troubleshooting

Learn More

Navigation menu

Search