Start Here: Helpdesk & Support Staff#
Audience: IT Helpdesk, Support Engineers, IT Administrators handling user requests
Prerequisites: Basic understanding of YubiKeys and authentication concepts
Outcome: Handle common user requests efficiently—PIN resets, lost keys, and enrollment support
Your Role#
As helpdesk or support staff, you’re the first point of contact for users experiencing issues with their YubiKeys. You need to know how to guide users through common tasks, handle lost device reports, and escalate appropriately.
Recommended Reading Path#
1. Understand User Workflows#
Learn what users do with Kleidia:
- End User Guide - What users see and do in the system
- YubiKey Lifecycle - Device states from enrollment to retirement
2. Common Support Tasks#
Master the procedures you’ll use most often:
- Administrator Guide - Admin interface for managing users and devices
- FIDO2 Management - WebAuthn credential management and troubleshooting
3. Incident Response#
Know what to do when things go wrong:
- Runbooks - Step-by-step procedures for common incidents:
- Lost or stolen YubiKey
- User leaves the organization
- PIN lockout recovery
Common Support Scenarios#
User Forgot Their PIN#
- User contacts helpdesk
- Verify user identity (follow your organization’s verification policy)
- Navigate to user’s YubiKey in Kleidia admin
- Use “Reset PIN” function
- Communicate new PIN securely to user
- User must change PIN on first use
📖 See: YubiKey Lifecycle for detailed procedure
User Lost Their YubiKey#
Immediate Actions:
- Verify user identity
- Mark device as lost in Kleidia
- Revoke all certificates on the device
- Disable FIDO2 credentials
Follow-up:
- Issue replacement YubiKey
- Enroll new device for user
- Generate new certificates
- Document incident
📖 See: Lost YubiKey Runbook
User Leaving the Organization#
- Receive notification from HR/manager
- Revoke all certificates on user’s YubiKey(s)
- Disable FIDO2 credentials
- Mark devices as available for re-assignment (or retire)
- Document in audit log
📖 See: User Departure Runbook
User Can’t Enroll YubiKey#
Check:
- Is the Kleidia Agent running? (
http://127.0.0.1:56123/.well-known/kleidia-agent) - Is the YubiKey inserted and recognized by the OS?
- Is the user logged into Kleidia with correct permissions?
- Is the YubiKey already registered to another user?
📖 See: Agent Installation for troubleshooting
Quick Reference Card#
| User Request | Action | Documentation |
|---|---|---|
| Forgot PIN | Reset via admin interface | YubiKey Lifecycle |
| Lost YubiKey | Revoke, disable, replace | Lost Key Runbook |
| New YubiKey | Enroll via web UI | End User Guide |
| Can’t authenticate | Check cert validity, PIN attempts | Troubleshooting |
| Leaving company | Revoke all, disable device | Departure Runbook |
| Agent not working | Verify agent service running | Agent Installation |
Escalation Guide#
Escalate to Operations/DevOps when:
- Kleidia web interface is unavailable
- Multiple users affected simultaneously
- Agent installation issues not resolved by reinstall
- Certificate signing failures (PKI issues)
Escalate to Security when:
- Suspected security incident
- Multiple lost device reports in short time
- Unauthorized access attempts detected in audit log
Next Steps#
- Practice in Test Environment: Get access to a POC deployment to practice workflows
- Bookmark Key Pages: Keep runbooks accessible for quick reference
- Know Your Escalation Path: Understand who to contact for different issue types