WebAuthn (Biometric)

WebAuthn enables passwordless biometric authentication using FIDO2-compliant hardware tokens, fingerprint readers, face recognition, and platform authenticators. This authentication method leverages public key cryptography to provide secure, phishing-resistant authentication without passwords.

WebAuthn is one of several authentication methods in the Light framework. See Password Authentication for traditional authentication, Two-Factor Authentication for TOTP-based 2FA, and OAuth and Social Login for third-party provider integration.

---

Overview

The WebAuthn implementation stores credentials as structured data in the User model's credential property. Each user can register multiple authenticators (e.g., fingerprint sensor, security key, face recognition) for flexible authentication options.

Key Components:

Component	Purpose
User.credential	Array property storing registered WebAuthn credentials
User::getWebAuthn()	GraphQL field exposing credential information
Light\Type\WebAuthn	GraphQL type wrapper for credential data
Controller\WebAuthnController	Handles credential registration and authentication mutations
Controller\AuthController	Integrates WebAuthn with login flow

After successful WebAuthn authentication, the system issues JWT tokens (see JWT Token System) and creates session records in UserLog, consistent with other authentication methods.

Sources: src/Model/User.php9 src/Model/User.php23 src/Model/User.php147-158

---

System Architecture

WebAuthn Component Integration

Key Integration Points:

• Controller\WebAuthnController: GraphQL mutations for credential management
• Controller\AuthController: Invokes WebAuthn verification during login
• Light\Model\User::credential: Array field storing credential data as JSON
• Light\Model\User::getWebAuthn(): Exposes credentials to GraphQL queries
• Light\Type\WebAuthn: Wraps credential data for GraphQL schema

Sources: src/Model/User.php9 src/Model/User.php23 src/Model/User.php147-158

---

Credential Storage

WebAuthn credentials are stored as a JSON array in the User model's credential property. Each array element represents a registered authenticator (e.g., fingerprint sensor, security key, face recognition).

User Model Schema

Credential Property Definition

Property	Type	Visibility	Description
credential	array	Database field	JSON array of WebAuthn credential objects
user_id	int	Database field	User identifier
username	string	Database field	Username displayed during authentication

The credential property is declared at src/Model/User.php23 as a PHP DocBlock property:

This property is persisted to the MySQL database as a JSON column, allowing each user to register multiple authenticators.

Credential Array Structure

Multiple Authenticators per User

Each credential object contains:

• Credential ID: Unique identifier for the authenticator
• Public Key: Public key used for signature verification
• Counter: Usage counter for clone detection
• User Handle: Internal user identifier mapping
• Attestation Data: Device attestation information (optional)

The exact structure is managed by the WebAuthn library implementation in Controller\WebAuthnController.

Sources: src/Model/User.php23

---

GraphQL Integration

Querying User Credentials

The User GraphQL type exposes registered WebAuthn credentials through the webAuthn field, which returns an array of Light\Type\WebAuthn objects.

Implementation: User::getWebAuthn()

Location: src/Model/User.php147-158

This method:

1. Iterates through the credential array property
2. Wraps each credential in a Light\Type\WebAuthn instance
3. Returns the array for GraphQL exposure

The #[Field] attribute (line 147) marks this method as a GraphQL field resolver.

GraphQL Query Example

The Light\Type\WebAuthn class (imported at src/Model/User.php9) wraps credential data for GraphQL schema exposure, providing type-safe access to credential properties.

Sources: src/Model/User.php9 src/Model/User.php147-158

---

Credential Registration Flow

WebAuthn credential registration follows a challenge-response protocol to securely bind an authenticator to a user account.

Registration Sequence

Registration Steps:

1. Challenge Generation: WebAuthnController generates a cryptographic challenge with relying party configuration
2. Client-Side Creation: Browser invokes navigator.credentials.create() with challenge and options
3. Authenticator Interaction: Hardware prompts user for biometric (fingerprint, face, etc.)
4. Attestation: Authenticator signs the credential with its private key, creating public key and attestation
5. Verification: Controller verifies attestation signature and validates challenge response
6. Storage: New credential is appended to User::credential array
7. Persistence: User record is saved to database with updated credential array

The credential array allows users to register multiple authenticators for redundancy (e.g., both fingerprint and security key).

Sources: src/Model/User.php23 src/Model/User.php147-158

---

Authentication Flow

WebAuthn authentication verifies user identity by validating a signature from a registered authenticator.

Authentication Sequence

Authentication Steps:

1. User Identification: Client submits username to identify which user is authenticating
2. Credential Retrieval: User::getWebAuthn() loads all registered credentials for the user
3. Challenge Generation: Server generates a unique challenge for this authentication attempt
4. Assertion Request: Browser requests authenticator to sign the challenge with a registered credential
5. Biometric Verification: User provides biometric authentication (fingerprint, face, etc.)
6. Signature Verification: Controller verifies assertion signature using stored public key from credential array
7. Counter Check: Validates authenticator counter to detect cloned devices
8. Token Issuance: On success, generates JWT access and refresh tokens (see JWT Token System)
9. Session Logging: Records authentication in UserLog with result="SUCCESS" and jti from JWT
10. Cookie Setting: Sets HTTP-only cookies with tokens, marks user as authenticated

The authentication process integrates with the standard JWT session management, creating the same session structure as password-based login.

Sources: src/Model/User.php147-158 src/Auth/Service.php28-80

---

Session Management

After successful WebAuthn authentication, the system creates a session identical to other authentication methods.

Session Creation Components

Component	Purpose	Reference
JWT Token	Access token (short-lived) and refresh token (long-lived)	JWT Token System
HTTP-Only Cookie	Stores tokens, protected from JavaScript access	JWT Token System
UserLog Record	Tracks session with jti, IP address, user agent	User Model and Sessions
Cache Entry	Revocation tracking for revoked_token_{jti}	JWT Token System

The Auth\Service class (see Auth Service) validates JWT tokens on subsequent requests, loading the user context:

From src/Auth/Service.php50-73:

WebAuthn authentication produces the same session structure as password login, enabling consistent session management across authentication methods.

Sources: src/Auth/Service.php50-73 src/Model/User.php201-204

---

Security Characteristics

Credential Storage Security

Security Aspect	Implementation
Storage Format	JSON array in MySQL database
Secrets	Only public keys stored; private keys remain in authenticator
Access Control	User can only query their own credentials via #[Field] annotation
Multiple Devices	Array structure supports multiple authenticators per user
Clone Detection	Counter verification identifies cloned authenticators

Authentication Security Features

Challenge-Response Protocol

Each authentication attempt uses a unique cryptographic challenge to prevent replay attacks. The challenge is generated server-side and must be signed by the authenticator's private key, which never leaves the hardware device.

Phishing Resistance

WebAuthn credentials are bound to the relying party's domain. The browser validates that the RP ID matches the origin before invoking the authenticator, preventing credentials from being used on phishing sites.

User Verification

WebAuthn requires user presence verification (biometric or button press), ensuring that someone physically interacting with the authenticator is present. This provides protection against remote attackers even if the device is compromised.

Authorization Integration

WebAuthn authentication integrates seamlessly with the RBAC system (see RBAC System):

From src/Auth/Service.php122-139:

After WebAuthn authentication:

• User's roles and permissions are loaded from the RBAC system
• GraphQL operations remain protected by #[Logged] and #[Right] annotations
• The authentication method does not affect authorization rules
• Administrators maintain their permission wildcards regardless of authentication method

Sources: src/Model/User.php147-158 src/Auth/Service.php122-139

---

Configuration

Environment Variables

Variable	Required	Default	Description
JWT_SECRET	Yes	-	Secret key for signing JWT tokens after authentication
DATABASE_*	Yes	-	Database connection credentials for User table

WebAuthn relies on the same JWT and database configuration as other authentication methods. The JWT_SECRET is used to sign access and refresh tokens after successful WebAuthn authentication.

From src/Auth/Service.php51:

Application Configuration

WebAuthn configuration is managed by Controller\WebAuthnController (not shown in provided files). The controller configures:

• Relying Party (RP) Entity: Application identifier and display name
• User Verification Requirements: Whether biometric is required vs. optional
• Attestation Preference: Level of device attestation required
• Timeout: Challenge timeout for registration and authentication

These settings are typically configured during application initialization and may be stored in the Config model (see Config Model and Settings).

Sources: src/Auth/Service.php51

---

Data Flow Summary

Sources: src/App.php631-685 src/Model/User.php147-158