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.

Prerequisites

• Python 3.10+ with fido2 (python-fido2 >= 2.0.0), flask, and cryptography libraries installed
• HTTPS-enabled web server (WebAuthn API requires secure context; localhost is exempt for development)
• FIDO2-compatible hardware security key (YubiKey 5 Series, SoloKeys, Titan Security Key) or platform authenticator
• Modern web browser supporting the WebAuthn API (Chrome 67+, Firefox 60+, Safari 14+, Edge 79+)
• Understanding of public key cryptography, challenge-response protocols, and HTTP session management

Workflow

Step 1: Relying Party Server Configuration

Configure the WebAuthn relying party (RP) identity and server:

• Define RP identity: Create a PublicKeyCredentialRpEntity with the relying party name (display name shown to users) and RP ID (the effective domain of the application). The RP ID must be a registrable domain suffix of the origin -- for example, example.com is valid for https://auth.example.com but other.com is not.
• Initialize Fido2Server: Instantiate the Fido2Server class from the python-fido2 library with the RP entity. The server handles challenge generation, attestation verification, and assertion validation.
• Configure attestation preference: Set the attestation conveyance preference to control whether the server requests proof of the authenticator's identity:
  • none: No attestation requested (simplest, recommended for most deployments)
  • indirect: Attestation may be provided but CA may anonymize it
  • direct: Full attestation chain from the authenticator's manufacturer
  • enterprise: Device-identifying attestation for managed environments
• Session management: Configure server-side sessions to store WebAuthn state between the begin and complete phases of registration/authentication ceremonies. Use secure, httponly cookies with SameSite=Strict.
• Credential storage: Design the database schema to store credential records: credential_id (binary), public_key (COSE key), sign_count (uint32 for clone detection), user_id, created_at, last_used, display_name, and transports (USB, NFC, BLE, internal).

Step 2: Registration Ceremony (Credential Creation)

Implement the WebAuthn registration flow to create new credentials:

• Begin registration: Call server.register_begin() with the user entity (PublicKeyCredentialUserEntity containing user ID, username, and display name), the list of existing credentials for the user (to prevent duplicate registration), and options for user_verification and authenticator_attachment.
• Authenticator selection criteria:
  • authenticator_attachment: cross-platform restricts to roaming authenticators (USB/NFC keys)
  • authenticator_attachment: platform restricts to built-in authenticators (Touch ID, Windows Hello)
  • Omitting this field allows both types
  • resident_key: required forces creation of a discoverable credential (passkey) stored on the authenticator
  • user_verification: required enforces PIN or biometric verification on the authenticator
• Client-side ceremony: The browser calls navigator.credentials.create() with the options from the server. The authenticator generates a new key pair, stores the private key in its secure element, and returns the public key, credential ID, attestation object, and client data JSON.

…