Registration/SSH/SSH-FIDO2-Quick-Start - Revision history

M Janczyk: /* Option B: Browser Setup (Chrome/Chromium/Brave) */

2026-01-12T13:30:33Z

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

← Older revision		Revision as of 15:30, 12 January 2026
Line 80:		Line 80:
	* Chrome/Chromium/Brave: <code>chrome://settings/securityKeys</code>		* Chrome/Chromium/Brave: <code>chrome://settings/securityKeys</code>

	[[File:Chrome_Fido2_1.png\|center\|600px\|Manage security keys - shows options for Create PIN, Sign-in data, Fingerprints, and Reset security key]]		[[File:Chrome_Fido2_1.png\|center\|600px\|thumb\|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!'''		'''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!'''
Line 88:		Line 88:
	Click '''Create a PIN''' and follow the prompts:		Click '''Create a PIN''' and follow the prompts:

	[[File:Chrome_Fido2_2.png\|center\|400px\|Create PIN dialog]]		[[File:Chrome_Fido2_2.png\|center\|400px\|thumb\|Create PIN dialog]]
	[[File:Chrome_Fido2_3.png\|center\|400px\|Enter new PIN]]		[[File:Chrome_Fido2_3.png\|center\|400px\|thumb\|Enter new PIN]]

	'''3. PIN Created Successfully:'''		'''3. PIN Created Successfully:'''

M Janczyk at 13:27, 12 January 2026

2026-01-12T13:27:23Z

Show changes

M Janczyk: M Janczyk moved page Registration/SSH/Yubikey-Quick-Start to Registration/SSH/SSH-FIDO2-Quick-Start

2025-12-03T15:38:34Z

M Janczyk moved page Registration/SSH/Yubikey-Quick-Start to Registration/SSH/SSH-FIDO2-Quick-Start

← Older revision	Revision as of 17:38, 3 December 2025
(No difference)

M Janczyk: /* SSH with Yubikey - Quick Start Guide */

2025-12-03T15:38:02Z

SSH with Yubikey - Quick Start Guide

Show changes

H Winkhardt: typo

2025-12-02T09:53:16Z

typo

← Older revision		Revision as of 11:53, 2 December 2025
Line 142:		Line 142:
	= Advanced Topics =		= Advanced Topics =

	== Using Multiple Yubikeys (Optional) ====		== Using Multiple Yubikeys (Optional) ==

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

M Janczyk at 19:14, 1 December 2025

2025-12-01T19:14:03Z

← Older revision		Revision as of 21:14, 1 December 2025
Line 3:		Line 3:
	This guide shows you how to secure your SSH keys with a Yubikey using FIDO2.		This guide shows you how to secure your SSH keys with a Yubikey using FIDO2.

	{\|style="background:#~~deffee~~; ~~width~~:~~100%~~;"		<div style="border: 3px solid #28a745; padding: 15px; background-color: #d4edda; margin: 10px 0;">
	\|style="padding:5px; background:#cef2e0; text-align:left"\|
	[[Image:Attention.svg\|center\|25px]]
	\|style="padding:5px; background:#cef2e0; text-align:left"\|
	'''Why FIDO2 SSH Keys?'''		'''Why FIDO2 SSH Keys?'''

Line 31:		Line 28:
	\| bwForCluster NEMO 2 \|\| style="background-color:#90EE90;" \| ✓		\| bwForCluster NEMO 2 \|\| style="background-color:#90EE90;" \| ✓
	\|}		\|}
			</div>
	\|}

	= Requirements =		= Requirements =
Line 91:		Line 88:
	== Step 3: Register Your Public Key ==		== Step 3: Register Your Public Key ==

	{\|style="background:#~~deffee~~; ~~width~~:~~100%~~;"		<div style="border: 3px solid #17a2b8; padding: 15px; background-color: #d1ecf1; margin: 10px 0;">
	\|style="padding:5px; background:#cef2e0; text-align:left"\|
	[[Image:Attention.svg\|center\|25px]]
	\|style="padding:5px; background:#cef2e0; text-align:left"\|
	'''FIDO2 SSH Keys work immediately without 2-factor authentication!'''		'''FIDO2 SSH Keys work immediately without 2-factor authentication!'''

	Unlike regular SSH keys, FIDO2 keys do not need to be "unlocked" with username/password.		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'''.		They work as soon as you register them as '''Interactive Keys'''.
			</div>
	\|}

	'''For bwUniCluster 3.0 and bwForCluster NEMO 2:'''		'''For bwUniCluster 3.0 and bwForCluster NEMO 2:'''

M Janczyk at 19:00, 1 December 2025

2025-12-01T19:00:55Z

← Older revision		Revision as of 21:00, 1 December 2025
Line 9:		Line 9:
	'''Why FIDO2 SSH Keys?'''		'''Why FIDO2 SSH Keys?'''

	FIDO2 SSH keys (~~ECDSA-SK and~~ ED25519-SK) offer significant advantages:		FIDO2 SSH keys (ED25519-SK) offer significant advantages:
	* '''No 2-factor unlock required''' - work immediately after registration		* '''No 2-factor unlock required''' - work immediately after registration
	* '''Hardware-protected''' - private key never leaves the Yubikey		* '''Hardware-protected''' - private key never leaves the Yubikey
	* '''Physical presence required''' - you must touch the key to authenticate		* '''Physical presence required''' - you must touch the key to authenticate

	* '''Works on bwUniCluster 3.0 and bwForCluster NEMO 2'''
			'''Note:''' ECDSA-SK keys are not supported on these clusters. Use ED25519-SK instead.

			{\| class="wikitable" style="text-align:center; margin-top:10px;"
			\|+ Cluster Support
			\|-
			! Cluster !! FIDO2 Support
			\|-
			\| bwUniCluster 3.0 \|\| style="background-color:#90EE90;" \| ✓
			\|-
			\| bwForCluster BinAC 2 \|\| style="background-color:#FFB6C1;" \| ✗
			\|-
			\| bwForCluster Helix \|\| style="background-color:#FFB6C1;" \| ✗
			\|-
			\| bwForCluster JUSTUS 2 \|\| style="background-color:#FFB6C1;" \| ✗
			\|-
			\| bwForCluster NEMO 2 \|\| style="background-color:#90EE90;" \| ✓
			\|}
	\|}		\|}

Line 91:		Line 108:
	</pre>		</pre>

	2. Copy the complete output (starts with <code>sk-ssh-ed25519~~@openssh.com</code> or <code>sk-ecdsa-sha2-nistp256~~@openssh.com</code>)		2. Copy the complete output (starts with <code>sk-ssh-ed25519@openssh.com</code>)

	3. Follow the [[Registration/SSH#Adding_a_new_SSH_Key\|SSH Key Registration Guide]] to:		3. Follow the [[Registration/SSH#Adding_a_new_SSH_Key\|SSH Key Registration Guide]] to:

M Janczyk: Created page with "= SSH with Yubikey - Quick Start Guide = This guide shows you how to secure your SSH keys with a Yubikey using FIDO2. {|style="background:#deffee; width:100%;" |style="padding:5px; background:#cef2e0; text-align:left"| 25px |style="padding:5px; background:#cef2e0; text-align:left"| '''Why FIDO2 SSH Keys?''' FIDO2 SSH keys (ECDSA-SK and ED25519-SK) offer significant advantages: * '''No 2-factor unlock required''' - work immediately after..."

2025-12-01T15:58:19Z

Created page with "= SSH with Yubikey - Quick Start Guide = This guide shows you how to secure your SSH keys with a Yubikey using FIDO2. {|style="background:#deffee; width:100%;" |style="padding:5px; background:#cef2e0; text-align:left"| center|25px |style="padding:5px; background:#cef2e0; text-align:left"| '''Why FIDO2 SSH Keys?''' FIDO2 SSH keys (ECDSA-SK and ED25519-SK) offer significant advantages: * '''No 2-factor unlock required''' - work immediately after..."

New page

= SSH with Yubikey - Quick Start Guide =

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

{|style="background:#deffee; width:100%;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
'''Why FIDO2 SSH Keys?'''

FIDO2 SSH keys (ECDSA-SK and 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
* '''Works on bwUniCluster 3.0 and bwForCluster NEMO 2'''
|}

= Requirements =

* A Yubikey (5 series or newer)
* OpenSSH 8.2 or newer
* Linux system with <code>yubikey-manager</code> and <code>openssh-client</code> packages

'''Check your OpenSSH version:'''
<pre>
ssh -V
ssh -Q PubkeyAcceptedAlgorithms | grep sk-ssh-ed25519@openssh.com
</pre>

'''Need help with installation?''' See the [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#ssh-and-yubikeys 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:

<pre>
ykman fido access change-pin
</pre>

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 [https://www.yubico.com/products/yubico-authenticator/ Yubico Authenticator] instead.

'''Forgot your PIN or need to reset?''' See the [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#troubleshooting 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 [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#creating-discoverable-ssh-keys resident keys documentation].

Connect your Yubikey and create a new SSH key:

<pre>
ssh-keygen -t ed25519-sk
</pre>

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 <code>id_ed25519_sk_bwunicluster</code> or <code>id_ed25519_sk_nemo2</code>
* '''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:
* <code>~/.ssh/id_ed25519_sk_bwunicluster</code> - key handle (encrypted credentials that require the Yubikey)
* <code>~/.ssh/id_ed25519_sk_bwunicluster.pub</code> - public key (this is what you'll upload)

'''Want keys stored on the Yubikey itself?''' See [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#creating-discoverable-ssh-keys resident keys documentation] for discoverable keys that can be copied to any machine.

== Step 3: Register Your Public Key ==

{|style="background:#deffee; width:100%;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
'''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:
<pre>
cat ~/.ssh/id_ed25519_sk_bwunicluster.pub
</pre>

2. Copy the complete output (starts with <code>sk-ssh-ed25519@openssh.com</code> or <code>sk-ecdsa-sha2-nistp256@openssh.com</code>)

3. Follow the [[Registration/SSH#Adding_a_new_SSH_Key|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:

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

'''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 <code>~/.ssh/config</code> to avoid typing the <code>-i</code> option every time:

<pre>
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
</pre>

Then simply connect with: <code>ssh bwuni</code> or <code>ssh nemo2</code>

See [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#ssh-configuration-for-fido2-secured-ssh-keys 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: <code>id_ed25519_sk_key1</code>
2. Create another key on your second Yubikey: <code>id_ed25519_sk_key2</code>
3. Register '''both public keys''' in bwIDM as Interactive Keys
4. Configure <code>~/.ssh/config</code> with multiple identities:

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

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 <code>yubikey-manager</code>:
*** Debian/Ubuntu: <code>sudo apt install yubikey-manager</code>
*** RHEL/Rocky/Alma: <code>sudo dnf install yubikey-manager</code>
** Install <code>openssh-client</code> if missing

* '''Old OpenSSH?'''
** Check version: <code>ssh -V</code>
** 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 [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#configure-yubikey-for-fido2 PIN reset guide]

'''Need more help?''' See the [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#troubleshooting complete troubleshooting guide].

= Learn More =

'''Cluster-Specific Documentation:'''
* [[Registration/SSH|Complete SSH Key Registration Guide for bwUniCluster/bwForCluster]]

'''Yubikey & FIDO2 SSH Documentation:'''
* [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey Comprehensive Yubikey Guide] - Setup, configuration, troubleshooting
** [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#creating-discoverable-ssh-keys Resident Keys] - Store keys directly on Yubikey
** [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#ssh-configuration-for-fido2-secured-ssh-keys SSH Config Examples] - Automate your SSH connections
** [https://gitlab.rz.uni-freiburg.de/escience-public/yubikey#yubikey-best-practices Backup Strategies] - Multi-key and recovery setups

'''Official Yubico Documentation:'''
* [https://developers.yubico.com/SSH/Securing_SSH_with_FIDO2.html Securing SSH with FIDO2] - Technical deep dive