implementing-hardware-security-key-authentication

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.