Download the PHP package r0073rr0r/laravel-webauthn without Composer

Laravel – Jetstream Livewire WebAuthn Components

A Laravel package that integrates seamlessly with Jetstream and Livewire to provide WebAuthn authentication — including support for biometric login, USB security keys, and passkeys.

📑 Table of Contents

• Requirements
• Installation
• Updating
• Setup
• Usage
  • Registration (WebAuthnRegister)
  • Login (WebAuthnLogin)
• Configuration
• Customization
• Security
• License
• Contributing

📋 Requirements

• PHP 8.2+
• Laravel 12.x
• Livewire 3.x
• Jestream 5.x
• OpenSSL extension for PHP
• Composer packages:
  • spomky-labs/cbor-php ^3.1
  • web-auth/webauthn-framework ^5.2

📦 Installation

Install the package via Composer:

If you encounter dependency errors, run:

Note: "web-auth/webauthn-framework": "^5.2" requires brick/math ^0.13, while newer Jetstream requires brick/math ^0.14. An update to version 5.3 is expected soon, which will resolve this issue, but the tag has not been created yet and the composer constraint cannot be changed.

Publish views and config files:

Publish all package resources (views, translations, and public assets) with a single command:

This will also copy the translation files to your lang/vendor/webauthn directory, where you can customize them.

Migrate database tables:

Note: The migration is safe to run even if the webauthn_keys table already exists. It will check if the table exists before creating it, and will add a unique constraint on credentialId if it doesn't already exist.

🔄 Updating

When updating the package to a new version, you should republish the configuration and translation files to ensure you have the latest changes:

The --force flag will overwrite existing files with the latest versions from the package, ensuring you have all new configuration options and translations.

Important: After updating, review the config/webauthn.php file for any new configuration options that may have been added.

⚙️ Setup

After publishing the assets, include the WebAuthn JavaScript file in your layout (e.g., in resources/views/layouts/app.blade.php & resources/views/layouts/guest.blade.php or wherever you have your main layout):

This script is required for the WebAuthn components to work properly.

🚀 Usage

Registration (WebAuthnRegister)

Add the component to your Blade view (I added it in resources/views/profile/show.blade.php):

This component allows users to register their WebAuthn device (fingerprint, Face ID, USB security key, etc.).

Login (WebAuthnLogin)

Add the component to your Blade view (I added it in resources/views/auth/login.blade.php after login form):

This component allows users to log in using their previously registered WebAuthn device.

⚙️ Configuration

The package configuration file is located at config/webauthn.php. After publishing, you can customize the following options:

Basic Configuration

Supported Algorithms

You can configure which cryptographic algorithms are allowed:

Rate Limiting

Protect against brute force attacks with configurable rate limiting:

Timeout Configuration

Configure the timeout for WebAuthn operations (in milliseconds):

Device Name Validation

Set minimum and maximum length for device names:

Audit Logging

Enable audit logging for security monitoring:

Log Channel Options:

• 'daily' - Creates a new log file each day (e.g., laravel-2025-01-07.log) in storage/logs/
• 'single' - Writes to a single log file (laravel.log)
• 'syslog' - Writes to system log
• 'errorlog' - Writes to PHP error log
• Custom channel - Use any channel defined in config/logging.php

Note: The 'daily' channel does NOT send emails. It only writes to log files. If you need email notifications, configure a custom log channel in config/logging.php that uses a mail driver.

Email Notifications for Audit Logs

If you want to receive email notifications for WebAuthn operations, you can configure a custom log channel with email support:

Step 1: Add a custom channel in config/logging.php:

Step 2: Configure the email channel in your .env:

Step 3: Make sure your Laravel mail configuration is set up correctly in .env:

Alternative: For more advanced email notifications (e.g., only on errors, formatted emails), you can create a custom channel with Slack, Discord, or other notification services:

Audit logs include:

• Key registrations (with user ID, key name, credential ID, AAGUID)
• Login attempts (successful and failed)
• Key deletions
• Errors with full context (IP, user agent, timestamp)

Example log entry:

Environment Variables

You can configure all options via environment variables in your .env file:

🎨 Customization

You can customize the view files after publishing them:

• resources/views/vendor/laravel-webauthn/livewire/web-authn-register.blade.php
• resources/views/vendor/laravel-webauthn/livewire/web-authn-login.blade.php

🔒 Security

WebAuthn is a modern standard for secure passwordless authentication. This package uses browser native WebAuthn APIs for maximum security.

Security Features

• Rate Limiting: Protects against brute force attacks with configurable limits
• Audit Logging: Comprehensive logging of all WebAuthn operations for security monitoring
• Replay Attack Protection: Sign counter validation prevents replay attacks
• Origin Validation: Ensures requests come from allowed origins only
• Challenge Validation: One-time challenges prevent replay attacks
• User Verification: Optional user verification requirement for enhanced security

Supported Authenticators

This package supports a wide range of WebAuthn authenticators:

• ✅ Chrome/Edge passkeys (biometric authentication) - EC2 P-256
• ✅ YubiKey 5 series (USB security keys) - EC2 P-256 or RSA
• ✅ Apple Touch ID / Face ID (via Safari) - EC2 P-256
• ✅ Other hardware security keys - Various algorithms (ES256, ES384, ES512, RS256)

📝 License

MIT License

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.