| name | implementing-hardware-security-key-authentication |
| description | Implements FIDO2/WebAuthn hardware security key authentication including registration ceremonies, authentication flows, YubiKey enrollment, and passkey migration strategies. Builds a complete relying party server using the python-fido2 library that supports cross-platform authenticators, resident key (discoverable credential) workflows, and user verification policies. Activates for requests involving FIDO2 implementation, WebAuthn registration, hardware security key enrollment, YubiKey integration, or passkey migration from password-based authentication.
|
| domain | cybersecurity |
| subdomain | identity-and-access-management |
| tags | ["FIDO2","WebAuthn","hardware-security-key","YubiKey","passkeys","passwordless-authentication","CTAP2"] |
| version | 1.0.0 |
| author | mukul975 |
| license | Apache-2.0 |
| atlas_techniques | ["AML.T0051","AML.T0054","AML.T0056"] |
| nist_ai_rmf | ["MEASURE-2.7","MEASURE-2.5","GOVERN-6.1","MAP-5.1"] |
| nist_csf | ["PR.AA-01","PR.AA-02","PR.AA-05"] |
Implementing Hardware Security Key Authentication
When to Use
- Deploying phishing-resistant multi-factor authentication (MFA) using FIDO2 hardware security keys for high-value accounts (administrators, developers, privileged users)
- Building a WebAuthn relying party server that supports both roaming authenticators (USB/NFC security keys) and platform authenticators (Windows Hello, Touch ID, Android biometrics)
- Migrating an existing password-based authentication system to support passkeys (discoverable credentials) as a primary or secondary authentication factor
- Enrolling YubiKey devices for an organization's workforce, including PIN setup, credential registration, and backup key provisioning
- Implementing passwordless authentication flows that comply with NIST SP 800-63B AAL3 (authenticator assurance level 3) requirements
Do not use without HTTPS in production (WebAuthn requires a secure origin), for systems where users cannot physically access a USB/NFC port, or as the sole authentication factor without a recovery mechanism for lost keys.
Common Misconfigurations & Verification
A registered FIDO2 key proves nothing if these gaps remain — each silently downgrades phishing resistance:
- Password fallback left enabled: users enroll a key but the login form still accepts password-only or TOTP, so an attacker phishes the weaker path. Confirm high-privilege accounts have password/TOTP disabled after the grace period and test that password login is rejected (HTTP 401, not a passkey prompt).
user_verification: discouraged: anyone holding the key authenticates with no PIN/biometric — it becomes single-factor. Verify the server sends user_verification: required and that authenticate_complete() enforces the UV flag in AuthenticatorData, not just presence.- Sign-count regression not handled: clone detection is silently skipped. Confirm the code rejects (or alarms) when the new
sign_count is ≤ the stored value, and that the event is logged.
- RP ID / origin too broad or mismatched: a wrong
rpId makes credentials usable across unintended subdomains. Verify rpId is the registrable suffix and that clientDataJSON.origin is validated server-side.
- No backup key / no enforced second authenticator: a lost key = lockout, pushing users back to email/SMS recovery that defeats phishing resistance. Confirm ≥2 credentials per account and that recovery never uses email/SMS alone.
- Attestation accepted blindly in "enterprise" deployments: verify the AAGUID against Yubico's published list and validate the attestation chain, otherwise a rogue/virtual authenticator passes as a genuine YubiKey.
