How to set up SSH login using a YubiKey

Require a physical security key to log in to your server

Logging in with a Yubikey

Security breaches are too common, and enhancing the security of server access is critical. One method is integrating hardware security keys, such as YubiKeys, for SSH authentication. This article will walk you through installing necessary software, generating a security-key-backed SSH key, configuring server and client settings, and troubleshooting common issues. By the end, you’ll have a setup that leverages one of the most secure forms of multi-factor authentication available today.

Step 1: Verify SSH Client and Server Compatibility

Ensure your SSH client (OpenSSH) is version 8.2 or later to support hardware security keys. Check the version by running:

ssh -V

Step 2: Install YubiKey Middleware

Install the necessary middleware and libraries to interface with the YubiKey. For macOS, use Homebrew:

brew install ykman libfido2

Step 3: Generate an SSH Key with YubiKey

Generate an SSH key pair using your YubiKey:

ssh-keygen -t ecdsa-sk -f ~/.ssh/id_ecdsa_sk

Follow the prompts to touch your YubiKey when required.

Step 4: Configure the Client’s SSH_SK_PROVIDER

Find the location of the libfido2.dylib library:

find /usr/local /opt/homebrew -name libfido2.dylib 2>/dev/null

Set the SSH_SK_PROVIDER environment variable to the path of libfido2.dylib:

export SSH_SK_PROVIDER=/opt/homebrew/lib/libfido2.dylib

Make this setting permanent by adding it to your .zshrc or .bash_profile:

echo 'export SSH_SK_PROVIDER=/opt/homebrew/lib/libfido2.dylib' >> ~/.zshrc
source ~/.zshrc

Step 5: Transfer the Public Key to the Server

Copy the public key to your server’s ~/.ssh/authorized_keys:

ssh-copy-id -i ~/.ssh/id_ecdsa_sk.pub username@server-address

Replace username@server-address with your actual server details.

Step 6: Server Configuration

Ensure the server’s SSH configuration (sshd_config) supports public key authentication:

sudo nano /etc/ssh/sshd_config

Confirm or add the following settings:

• PubkeyAuthentication yes
• PasswordAuthentication no (optional, if disabling password login)
• AuthenticationMethods publickey (optional, restricts to public key only)

Restart the SSH service to apply changes:

sudo systemctl restart sshd

Step 7: Test SSH Connection

Attempt to connect to your server using your new YubiKey-backed SSH key:

ssh -i ~/.ssh/id_ecdsa_sk username@server-address

If you encounter errors, increase verbosity for troubleshooting:

ssh -v -i ~/.ssh/id_ecdsa_sk username@server-address

Troubleshooting

• Check ~/.ssh/authorized_keys on the server to ensure the key was added correctly.
• Verify correct permissions on the server and client for .ssh directories and files.
• Consult verbose SSH output for specific error messages and adjust configurations accordingly.

This guide should help you set up SSH access using a YubiKey across different systems. It addresses key generation, middleware installation, server and client configuration, and basic troubleshooting steps. If any issues arise during setup, revisiting the verbose SSH logs often provides crucial clues for resolving them.