Secure Mail Client | Academy
All Topics Beginner Intermediate Advanced Download
Intermediate 30 minutes

YubiKey Authentication Troubleshooting

Authentication Protocols Overview

YubiKeys support multiple authentication protocols, each with its own set of potential issues. Before troubleshooting specific problems, it's helpful to understand which protocol you're using:

  • FIDO2/WebAuthn

    Modern web authentication standard used for passwordless or 2FA login to websites and services. Look for prompts to "insert security key" or "tap security key."

  • U2F

    Predecessor to FIDO2, used primarily for two-factor authentication in web browsers. Similar user experience to FIDO2 but with more limited functionality.

  • OpenPGP

    Used for email encryption, digital signatures, and authentication. Requires PIN entry for operations and typically works with GnuPG (GPG) software.

  • PIV

    Personal Identity Verification standard used primarily in enterprise environments for smart card authentication to systems and services.

  • OTP

    One-Time Password generation, either as Yubico OTP (touch-triggered long codes) or OATH-TOTP (time-based 6-digit codes like Google Authenticator).

FIDO2/WebAuthn Authentication Issues

FIDO2/WebAuthn is the modern standard for secure web authentication. Here's how to troubleshoot common issues:

Registration Problems

  • YubiKey not detected during registration:
    • Check that your YubiKey model supports FIDO2 (YubiKey 5 series and Security Key series do)
    • Ensure your browser has the required permissions (look for prompts in the address bar)
    • Try a different USB port or browser (Chrome has the best support)
    • Verify WebAuthn is enabled in browser settings (see our Application Integration guide)
  • Registration fails with errors:
    • "Already registered" errors indicate your YubiKey is already registered with that service
    • "Operation timed out" usually means you didn't touch the YubiKey when prompted
    • Some services limit the number of security keys that can be registered
    • Try registering in an incognito/private browsing window to avoid extension conflicts
  • Touch not recognized during registration:
    • Make sure you're touching the correct contact point (metal part) on your YubiKey
    • The touch must occur while the browser is waiting for the touch (usually indicated by a blinking YubiKey)
    • Some YubiKey models have more sensitive touch sensors than others
    • Hold your touch longer (1-2 seconds) rather than just tapping

Login Problems

  • YubiKey not recognized during login:
    • Ensure you're using the same YubiKey you registered with the service
    • Try using the same browser you used during registration
    • Check that your browser still has the necessary permissions
    • Restart your browser and try again
  • Login fails with "security key not recognized":
    • The security key may have been removed from your account (perhaps you reset it)
    • If you've reset your YubiKey since registration, you'll need to re-register it
    • Some services require periodic re-authentication with backup methods
    • Use your backup authentication method and re-register the YubiKey
  • PIN issues with FIDO2:
    • For resident keys (passwordless login), a PIN is required during setup
    • If you've forgotten your FIDO2 PIN, you'll need to reset the FIDO2 application
    • Use YubiKey Manager to reset the FIDO2 application (this will remove all FIDO2 credentials)
    • After resetting, you'll need to re-register with all services

Reset FIDO2 Application

If you need to reset the FIDO2 application on your YubiKey (for example, if you've forgotten your PIN), you can do this with YubiKey Manager. WARNING: This will delete all FIDO2 credentials stored on your YubiKey.

  1. Download and install YubiKey Manager
  2. Insert your YubiKey
  3. Open YubiKey Manager and select your YubiKey
  4. Go to Applications > FIDO2
  5. Click "Reset FIDO"
  6. Follow the prompts to confirm the reset

After resetting, you'll need to re-register your YubiKey with all services where you were using FIDO2/WebAuthn authentication.

OpenPGP Authentication Issues

OpenPGP is commonly used for email encryption, digital signatures, and SSH authentication. Here's how to troubleshoot OpenPGP issues:

PIN and Admin PIN Issues

  • PIN lockout:
    • After 3 incorrect PIN attempts, the PIN is blocked
    • Use the Admin PIN to unblock the regular PIN
    • Run gpg --card-edit, then admin, then unblock
    • If you've forgotten your Admin PIN, you'll need to reset the OpenPGP application
  • Admin PIN lockout:
    • After 3 incorrect Admin PIN attempts, the entire OpenPGP application is blocked
    • You'll need to reset the OpenPGP application completely
    • This will erase all OpenPGP keys on the YubiKey
    • See our detailed YubiKey Recovery and Reset guide
  • PIN not being accepted (but not locked):
    • Verify you're using the correct PIN (default is "123456")
    • Check if Num Lock is enabled/disabled on your keyboard
    • Some PIN entry dialogs can be confusing - ensure you're entering the PIN, not a passphrase
    • Try changing your PIN with gpg --card-edit, then admin, then passwd

Key Usage Problems

  • OpenPGP keys not detected:
    • Run gpg --card-status to check if your YubiKey is detected
    • Ensure GnuPG is properly installed and updated
    • Check if the OpenPGP application is enabled on your YubiKey with YubiKey Manager
    • Try using a different USB port or computer
  • Public key not found:
    • Even when using keys on a YubiKey, the corresponding public keys must be in your keyring
    • Import the public key with gpg --import yourkey.asc
    • Run gpg --list-keys to verify the public key is in your keyring
    • Ensure the key IDs on the YubiKey match the public keys in your keyring
  • Signature/encryption operations fail:
    • Check if the correct subkeys are loaded on the YubiKey
    • Verify that the keys have the proper capabilities (signing, encryption, authentication)
    • Ensure the keys haven't expired
    • Try restarting the GPG agent: gpgconf --kill gpg-agent

GPG Software Issues

  • No pinentry dialog appears:
    • The pinentry program may not be properly configured
    • On Windows, check if Kleopatra or GPA is running for PIN entry
    • On macOS/Linux, ensure pinentry is installed and configured in ~/.gnupg/gpg-agent.conf
    • Restart the GPG agent after making configuration changes
  • Card error or not available:
    • Ensure the YubiKey is fully inserted
    • Try restarting the PC-/SC daemon (smart card services)
    • On Windows: restart the "Smart Card" service
    • On Linux: sudo systemctl restart pcscd
    • On macOS: sudo pkill -1 pcscd

SSH Authentication Issues

YubiKeys can be used for SSH authentication in multiple ways: via OpenPGP, PIV, or FIDO2. Each method has different troubleshooting approaches:

OpenPGP-based SSH Authentication

  • SSH key not recognized:
    • Ensure the authentication subkey is loaded on the YubiKey
    • Check that GPG agent is configured for SSH: enable-ssh-support in gpg-agent.conf
    • Set the correct environment variable: export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)
    • Verify the key is available with ssh-add -L
  • GPG agent not providing SSH keys:
    • Check if GPG agent is running: gpg-connect-agent /bye
    • Restart GPG agent: gpgconf --kill gpg-agent && gpg-agent --daemon
    • Ensure the GPG agent configuration is correct
    • Make sure no other SSH agents are running (e.g., ssh-agent)

PIV-based SSH Authentication

  • PKCS#11 module issues:
    • PIV-based SSH requires the OpenSC PKCS#11 module
    • Ensure OpenSC is properly installed
    • Verify the correct path to the PKCS#11 module in your SSH configuration
    • On macOS: /usr/local/lib/opensc-pkcs11.so
    • On Linux: /usr/lib/x86_64-linux-gnu/opensc-pkcs11.so
    • On Windows: C:\Program Files\OpenSC Project\OpenSC\pkcs11\opensc-pkcs11.dll
  • Certificate configuration problems:
    • Ensure the PIV certificate is properly loaded in slot 9a (authentication)
    • Use YubiKey Manager to check the certificate status
    • Generate a new authentication key and certificate if needed
    • Verify the certificate format is compatible with SSH

FIDO2-based SSH Authentication

  • OpenSSH version compatibility:
    • FIDO2 SSH support requires OpenSSH 8.2 or newer
    • Check your SSH version with ssh -V
    • If your SSH version is too old, update it or use OpenPGP/PIV methods instead
  • Key generation and usage issues:
    • Use ssh-keygen -t ecdsa-sk or ssh-keygen -t ed25519-sk to generate FIDO2 SSH keys
    • The -sk suffix is required for security key support
    • When connecting, you'll need to touch the YubiKey when prompted
    • Use ssh -v for verbose output to diagnose connection issues
  • PIN-related problems:
    • Use ssh-keygen -t ed25519-sk -O resident -O verify-required to require PIN verification
    • If you've forgotten your FIDO2 PIN, you'll need to reset the FIDO2 application
    • PIN issues can prevent key generation and usage

OTP Authentication Issues

YubiKeys support various One-Time Password (OTP) authentication methods. Here's how to troubleshoot common OTP issues:

Yubico OTP Issues

  • OTP not recognized by service:
    • Ensure your YubiKey is registered with the service you're using
    • Check that you're using the correct slot (typically slot 1 by default)
    • Verify the service supports Yubico OTP authentication
    • Some services require special integration or plugins for Yubico OTP
  • OTP not being output:
    • Try a different USB port
    • Ensure the YubiKey is being recognized as a keyboard device
    • Check if your system has unusual keyboard layout settings
    • Verify the slot is programmed with Yubico OTP using YubiKey Manager
  • OTP validation failure:
    • Network connectivity issues may prevent OTP validation
    • Validation servers may be temporarily unavailable
    • The OTP may have been used already (replay attack protection)
    • There may be a clock synchronization issue with the YubiCloud service

OATH-TOTP Issues (Time-based OTP)

  • Incorrect codes generated:
    • Check if your computer's clock is synchronized correctly
    • TOTP relies on accurate time synchronization
    • Verify the correct account is selected in the authenticator app
    • Some services have clock skew tolerance settings
  • Missing TOTP credentials:
    • Use Yubico Authenticator to verify OATH credentials are loaded on the YubiKey
    • Re-add the TOTP credential if it's missing or corrupted
    • Check if you're using the correct YubiKey (if you have multiple)
    • Some credentials may have been removed if you've reset the OATH application
  • Yubico Authenticator app issues:
    • Update to the latest version of Yubico Authenticator
    • Try both NFC and USB connections if your YubiKey supports both
    • On mobile devices, ensure proper permissions are granted to the app
    • Restart the app if it's not detecting the YubiKey

PIV Authentication Issues

Personal Identity Verification (PIV) is often used in enterprise environments. Here's how to troubleshoot PIV issues:

Certificate Issues

  • Certificate not recognized:
    • Verify the certificate is properly loaded in the correct PIV slot
    • Use YubiKey Manager to check the certificate status
    • Ensure the certificate chain is trusted by your system
    • Check if the certificate has expired or been revoked
  • Smart card services problems:
    • On Windows, verify that the Smart Card service is running
    • On macOS, check if the PC-/SC daemon is active
    • On Linux, ensure pcscd is installed and running
    • Try restarting the smart card service if you're having issues
  • PIN issues with PIV:
    • Default PIV PIN is "123456"
    • After 3 incorrect PIN attempts, the PIN is blocked
    • Use the PUK to unblock the PIN (default PUK is "12345678")
    • If both PIN and PUK are blocked, you'll need to reset the PIV application completely

Middleware and System Integration

  • Smart card middleware problems:
    • PIV often requires specific middleware such as OpenSC
    • Ensure the middleware is properly installed and configured
    • On Windows, verify that the YubiKey minidriver is installed
    • Some applications require specific PKCS#11 providers
  • Windows logon issues:
    • PIV can be used for Windows logon, but requires proper certificate setup
    • The certificate must be issued by a trusted CA in the domain
    • Group Policy settings may affect smart card logon behavior
    • Check Event Viewer for smart card logon errors
Back to Troubleshooting Hub

In This Module

Share This Module

Related Modules

YubiKey Troubleshooting Guide

YubiKey Hardware Setup

YubiKey OpenPGP Recovery and Reset