Laravel Biometric Auth

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

🧪 Testing

Run PHPUnit tests using Orchestra Testbench:

vendor/bin/phpunit

📄 License

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