hashbrackets / laravel-biometric-auth

v1.0.0 2026-09-30 15:01 UTC

Requires

• php: ^8.2
• illuminate/auth: ^10.0|^11.0|^12.0|^13.0
• illuminate/contracts: ^10.0|^11.0|^12.0|^13.0
• illuminate/database: ^10.0|^11.0|^12.0|^13.0
• illuminate/http: ^10.0|^11.0|^12.0|^13.0
• illuminate/routing: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0
• paragonie/constant_time_encoding: ^2.6|^3.0
• symfony/process: ^6.0|^7.0|^8.0
• web-auth/webauthn-lib: ^4.8|^5.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

MIT

• HashBrackets

• Authentication
• laravel
• Passwordless
• Fingerprint
• biometric
• FIDO2
• webauthn
• faceid
• passkeys
• windows-hello

Published on Packagist.org on 2026-09-30 15:42 UTC

README

Laravel Biometric Auth is a production-ready Laravel package providing passwordless biometric authentication for Laravel applications using WebAuthn / FIDO2 standards.

Allow your application users to register and log in seamlessly using Fingerprint sensors, Touch ID, Face ID, Windows Hello, Android Biometrics, or Hardware Security Keys (YubiKey) — without typing passwords, emails, or OTPs.

🔒 Security Guarantee

Important

No biometric data (fingerprints, facial scans, etc.) is ever stored or transmitted to your server. Biometric verification takes place locally on the user's secure device hardware (Secure Enclave / TPM). The device generates cryptographic public/private key pairs and only public key assertions are sent to the Laravel backend.

🚀 Requirements

• PHP: 8.2 or higher
• Laravel: 10.x, 11.x, or 12.x
• HTTPS connection (or localhost for local development) as required by browser WebAuthn security specifications.

📦 Installation

Install the package via Composer:

composer require hashbrackets/laravel-biometric-auth

Run the interactive package installer command:

php artisan biometric:install

This command will automatically:

• Publish the configuration file config/biometric-auth.php
• Publish the migration file database/migrations/create_biometric_credentials_table.php
• Publish Blade components & views
• Publish the JavaScript SDK assets to public/vendor/biometric-auth/biometric-auth.js

Next, run the database migrations:

php artisan migrate

🛠️ User Model Setup

Add the BiometricAuthenticatable interface and HasBiometricCredentials trait to your User model (app/Models/User.php):

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use HashBrackets\LaravelBiometricAuth\Contracts\BiometricAuthenticatable;
use HashBrackets\LaravelBiometricAuth\Traits\HasBiometricCredentials;

class User extends Authenticatable implements BiometricAuthenticatable
{
    use HasBiometricCredentials;

    // ...
}

🎨 Layout Setup & Blade Directives

Include @biometricScripts and the CSRF meta tag in your Blade layout template (e.g. resources/views/layouts/app.blade.php):

<!DOCTYPE html>
<html>
<head>
    <!-- Required CSRF token -->
    <meta name="csrf-token" content="{{ csrf_token() }}">
</head>
<body>
    @yield('content')

    <!-- Include Biometric JavaScript SDK -->
    @biometricScripts
</body>
</html>

🧩 Usage & Blade Components

1. Passwordless Login Button

Place the <x-biometric-login /> component anywhere on your login page:

<x-biometric-login 
    text="Login With Fingerprint" 
    redirect="/dashboard" 
    class="btn btn-primary" />

2. Register Biometric Device Button

Place the <x-biometric-register /> component inside an authenticated user's profile/settings page:

<x-biometric-register 
    text="Enable Fingerprint Login" 
    device-name="My MacBook Touch ID" 
    class="btn btn-success" />

3. Device Management Table

Display a list of registered devices with a "Remove Device" action:

<x-biometric-devices />

Or access the standalone management page built into the package at: /biometric/devices

💻 JavaScript SDK

The package bundles a lightweight, zero-dependency JavaScript SDK (BiometricAuth).

// 1. Register a new biometric device
BiometricAuth.register({
    deviceName: 'Work Laptop',
    redirect: '/profile'
}).then(result => {
    console.log('Biometric device registered!', result);
}).catch(err => {
    console.error('Registration failed:', err.message);
});

// 2. Passwordless Biometric Login
BiometricAuth.login({
    redirect: '/dashboard'
}).then(result => {
    console.log('Logged in successfully!', result);
}).catch(err => {
    console.error('Login failed:', err.message);
});

// 3. Remove a device credential
BiometricAuth.removeDevice(credentialId).then(result => {
    console.log('Device removed');
});

🛡️ Middleware Protection

Protect confidential or sensitive routes by requiring biometric authentication:

use Illuminate\Support\Facades\Route;

Route::middleware(['auth', 'biometric.auth'])->group(function () {
    Route::get('/admin/dashboard', function () {
        return view('admin.dashboard');
    });
});

⚙️ Configuration (config/biometric-auth.php)

return [
    'enabled' => env('BIOMETRIC_AUTH_ENABLED', true),

    'relying_party' => [
        'name' => env('BIOMETRIC_RP_NAME', env('APP_NAME', 'Laravel Application')),
        'id' => env('BIOMETRIC_RP_ID', parse_url(env('APP_URL', 'http://localhost'), PHP_URL_HOST)),
    ],

    'timeout' => 60000, // milliseconds
    'challenge_expiration' => 300, // seconds

    'user_verification' => 'required', // 'required', 'preferred', or 'discouraged'
    'attestation' => 'none', // 'none', 'indirect', or 'direct'

    'routes' => [
        'enabled' => true,
        'prefix' => 'biometric',
        'middleware' => ['web'],
    ],

    'redirects' => [
        'login' => '/dashboard',
        'register' => '/profile',
    ],
];

🌐 Browser & Device Compatibility

Platform / Browser	WebAuthn Support	Biometric Hardware
macOS (Safari, Chrome, Edge)	✅ Yes	Touch ID
iOS / iPadOS (Safari, Chrome)	✅ Yes	Face ID / Touch ID
Windows 10/11 (Edge, Chrome)	✅ Yes	Windows Hello (Face / Fingerprint / PIN)
Android (Chrome, Firefox)	✅ Yes	Fingerprint / Face Unlock
Linux (Chrome, Firefox)	✅ Yes	USB Security Keys (YubiKey, Titan)

🧪 Testing

Run PHPUnit tests using Orchestra Testbench:

vendor/bin/phpunit

📄 License

The MIT License (MIT). Please see LICENSE for more information.