End User Guide#

Audience: End Users
Prerequisites: Kleidia account, YubiKey device
Outcome: Use Kleidia to manage your YubiKey devices

Getting Started#

First Time Setup#

  1. Install Agent (if not already installed by IT)

    • See Agent Installation Guide for detailed instructions
    • End users: Follow the “End User Installation” section
    • IT administrators: Follow the “Enterprise Deployment” section
    • Agent runs automatically in background as system service

  2. Log In

    • Navigate to your organization’s Kleidia URL (e.g., https://kleidia.example.com)
    • Enter your username and password
    • Click “Log In”

  3. Verify Agent Connection

    • After logging in, check that the agent is connected
    • You should see “Agent Connected” status in the dashboard
    • If not connected, see Agent Installation Guide

  4. Register Your First YubiKey

    • Connect YubiKey to your computer
    • Navigate to “Register YubiKey” page
    • Follow registration wizard

Managing Your YubiKeys#

View Your YubiKeys#

  1. Navigate to Dashboard → My YubiKeys
  2. View list of all your registered YubiKeys
  3. See device status, serial numbers, and details

Register a New YubiKey#

  1. Connect YubiKey to your computer
  2. Navigate to Dashboard → Register YubiKey
  3. System automatically detects connected YubiKey
  4. Enter device information:
    • Device name (optional)
    • PIN (if setting up new device)
    • PUK (if setting up new device)
  5. Click “Register Device”
  6. Device appears in your YubiKeys list

View YubiKey Details#

  1. Navigate to My YubiKeys
  2. Click on a YubiKey device
  3. View detailed information:
    • Serial number
    • Device status
    • Certificate information
    • PIN/PUK status
    • Management key status

PIN and PUK Management#

Change PIN#

  1. Navigate to My YubiKeys
  2. Select your YubiKey device
  3. Click “PIN & PUK” tab
  4. Enter current PIN
  5. Enter new PIN
  6. Confirm new PIN
  7. Click “Change PIN”
  8. Operation completes automatically

Change PUK#

  1. Navigate to My YubiKeys
  2. Select your YubiKey device
  3. Click “PIN & PUK” tab
  4. Enter current PUK
  5. Enter new PUK
  6. Confirm new PUK
  7. Click “Change PUK”
  8. Operation completes automatically

Unblock PIN#

If your PIN is blocked:

  1. Navigate to My YubiKeys
  2. Select your YubiKey device
  3. Click “Advanced” tab
  4. Enter PUK
  5. Enter new PIN
  6. Confirm new PIN
  7. Click “Unblock PIN”

Certificate Management#

Generate Certificate#

  1. Navigate to My YubiKeys
  2. Select your YubiKey device
  3. Click “Certificate” tab
  4. Enter your PIN when prompted
  5. Click “Generate Certificate”
  6. System automatically generates CSR on YubiKey with subject yubikey-<serial-number>
  7. System signs certificate via OpenBao PKI
  8. Certificate imported to YubiKey automatically
  9. Certificates ready for use

Note: Certificate details (subject, issuer, validity) are automatically generated by the system. Users only need to provide their PIN. The certificate subject is automatically set to yubikey-<serial-number> where <serial-number> is your YubiKey’s serial number.

View Certificates#

  1. Navigate to My YubiKeys
  2. Select your YubiKey device
  3. View certificate information:
    • Certificate subject
    • Issuer
    • Validity period
    • Serial number
    • PIV slot

Note: Certificate revocation is controlled by administrators. Users cannot revoke certificates.

Device Management#

Check Device Status#

  1. Navigate to My YubiKeys
  2. View device status indicators:
    • Active: Device is registered and active
    • Connected: Device is currently connected
    • Disconnected: Device is not connected

Reset Device#

⚠️ WARNING: This will erase all PIV data on the YubiKey.

  1. Navigate to My YubiKeys
  2. Select your YubiKey device
  3. Click “Advanced” tab
  4. Click “Delete Yubikey”
  5. Confirm reset
  6. PIV application reset to factory defaults
  7. Device removed from system

Troubleshooting#

Agent Not Detected#

Symptom: System cannot detect agent on your workstation.

Solutions:

  1. Verify agent is installed and running
  2. Check agent is running on localhost:56123
  3. Refresh browser page
  4. Check browser console for errors
  5. Restart agent if needed

YubiKey Not Detected#

Symptom: System cannot detect your YubiKey.

Solutions:

  1. Verify YubiKey is connected to computer
  2. Check YubiKey is inserted properly
  3. Try different USB port
  4. Refresh device list

Note: The agent installer includes ykman (YubiKey Manager CLI) - no separate installation required.

Operation Failed#

Symptom: PIN/PUK change or certificate operation fails.

Solutions:

  1. Verify correct PIN/PUK entered
  2. Check YubiKey is connected
  3. Check YubiKey is not locked
  4. Try operation again
  5. Contact administrator if issue persists

Best Practices#

  • ✅ Keep your PIN and PUK secure
  • ✅ Change default PIN/PUK immediately
  • ✅ Use strong PINs (6-8 digits)
  • ✅ Keep YubiKey firmware updated
  • ✅ Backup important certificates
  • ✅ Report lost or stolen devices immediately

Getting Help#

  • Check this documentation
  • Contact your system administrator
  • Review troubleshooting section
  • Check system status page
Backward Administrator Guide Agent Installation Forward