Webauthn Laravel Package

Technical Evaluation

Architecture Fit

• Pros:

  • Native Laravel Integration: Designed for Laravel 12+ with typed HTTP requests, aligning with Laravel’s ecosystem (e.g., Eloquent, middleware, Octane compatibility).
  • Modular Design: Extends Laravel’s authentication stack via a custom eloquent-webauthn driver, enabling seamless fallback to password auth (password_fallback: true).
  • WebAuthn Best Practices: Implements FIDO2/CTAP standards (attestation/assertion ceremonies) with support for resident keys (passwordless login), biometrics, and security keys.
  • OpenSSL/Sodium Support: Leverages PHP’s native crypto extensions for performance and security (optional EdDSA via Sodium or paragonie/sodium_compat).
  • Contract-Driven: Uses WebAuthnAuthenticatable contract and WebAuthnAuthentication trait for clean, reusable user model integration.

• Cons:

  • Superseded by Official Package: laravel/passkeys is now the maintained standard. This package’s archival status introduces technical debt risk (e.g., unpatched vulnerabilities, lack of Laravel 13+ compatibility).
  • Tight Coupling: Custom migration/table schema for WebAuthn credentials may conflict with future Laravel auth updates or multi-tenant architectures.
  • CSRF Assumptions: WebAuthn routes disable CSRF by default, requiring manual handling (e.g., via @laragear/webpass JS library or custom middleware).

Integration Feasibility

• Laravel 12+ Compatibility: Confirmed support for PHP 8.3+ and Laravel 12+, but no guarantees for future versions (e.g., Laravel 13’s auth changes).
• Database Schema: Requires a dedicated webauthn_credentials table (or customizable variant). Migration conflicts possible if using other auth packages (e.g., Sanctum, Passport).
• Frontend Dependencies: Relies on @laragear/webpass (separate npm package) for client-side WebAuthn flows. Alternative: Manual JS implementation using the WebAuthn API.
• Octane Support: Optimized for Laravel Octane (Swoole/RoadRunner), but requires testing under high concurrency.

Technical Risk

Key Questions

1. Why Use This Over laravel/passkeys?

   • Legacy system constraints (e.g., existing laragear/webauthn dependencies).
   • Need for resident keys (one-tap login) or custom attestation logic not covered by the official package.
   • Recommendation: Use only for short-term PoC; migrate to laravel/passkeys ASAP.

2. How Will This Scale?

   • Credential Storage: Test performance with millions of WebAuthn credentials (indexing id/user_id is critical).
   • Concurrency: Octane support is good, but ensure openssl_* functions are thread-safe under load.
   • Recommendation: Benchmark with laravel/horizon or Swoole workers.

3. Fallback Auth Strategy

   • How will password fallback (password_fallback: true) interact with existing auth (e.g., Sanctum API tokens)?
   • Recommendation: Test edge cases (e.g., rate-limited password attempts during WebAuthn failures).

4. Compliance

   • Does this meet FIDO2 certification requirements for production use?
   • Recommendation: Validate against FIDO Alliance guidelines.

5. Long-Term Maintenance

   • Plan for deprecation: How will you sunset this package when migrating to laravel/passkeys?
   • Recommendation: Use feature flags to isolate laragear/webauthn logic.

Integration Approach

Stack Fit

• Backend: Laravel 12+ (PHP 8.3+), with ext-openssl (required) and ext-sodium (recommended).
• Frontend: Vanilla JS (via @laragear/webpass) or custom WebAuthn API calls. Frameworks (React/Vue) require manual integration.
• Database: MySQL/PostgreSQL/SQLite (supports the published migration).
• Infrastructure: Works with traditional PHP-FPM or Laravel Octane (Swoole/RoadRunner).

Migration Path

1. Assessment Phase:

   • Audit existing auth stack (e.g., Breeze, Jetstream, Sanctum) for conflicts.
   • Test WebAuthn support in target browsers/devices (e.g., Chrome 89+, Safari 15.4+).

2. PoC Implementation:

   • Install via composer require laragear/webauthn.
   • Run php artisan webauthn:install to publish config/migration.
   • Implement WebAuthnAuthenticatable in the User model.
   • Configure auth.php with eloquent-webauthn driver.

3. Gradual Rollout:

   • Phase 1: Enable WebAuthn for a subset of users (e.g., via feature flag).
   • Phase 2: Replace password login with WebAuthn for new users (use userless() for resident keys).
   • Phase 3: Deprecate password fallback (password_fallback: false) after adoption threshold.

4. Migration to laravel/passkeys:

   • Use a dual-write period: Store credentials in both webauthn_credentials and passkeys tables.
   • Backfill existing credentials using the official migration guide.
   • Sunset laragear/webauthn routes/controllers post-migration.

Compatibility

Sequencing

1. Prerequisites:

   • Enable ext-openssl and ext-sodium (or paragonie/sodium_compat).
   • Update Laravel to 12.x (PHP 8.3+).

2. Core Setup:

   • Publish config/migration: php artisan webauthn:install.
   • Run migrations: php artisan migrate.

3. User Model:

   • Add WebAuthnAuthenticatable contract and WebAuthnAuthentication trait.

4. Routing:

   • Register WebAuthn routes in web.php (disable CSRF):

     WebAuthnRoutes::register()->withoutMiddleware(VerifyCsrfToken::class);
     

5. Controllers:

   • Implement AttestationRequest/AttestedRequest for registration.
   • Implement AssertedRequest for login (e.g., public function login(AssertedRequest $request)).

6. Frontend:

   • Integrate @laragear/webpass or use native WebAuthn API:

     // Example: Resident key registration
     const { success } = await Webpass.attest("/webauthn/register/options", "/webauthn/register");
     

7. Testing:

   • Validate attestation/assertion flows with:
     • Local testing: [WebAuthn.io](https://web