README

A simple and elegant two-factor authentication package for Laravel 12 using Livewire and Flux components. Built to work seamlessly with Laravel 12's authentication stack.

Overview

Laravel 2FA provides an easy way to add Google Authenticator compatible two-factor authentication to your Laravel 12 application. Built with Livewire and Flux components, it offers a modern, interactive user experience with minimal configuration.

Features

🔒 Google Authenticator compatible (TOTP)
⚡ Livewire-powered interactive components
🎨 Beautiful UI with Flux components
🌓 Full dark mode support
🛠️ Simple integration with existing authentication systems
🔑 Recovery codes for account access backup
🛡️ On-demand password and 2FA confirmation modals
🔄 Compatible with Laravel 12 and Livewire 3

Requirements

PHP 8.2+
Laravel 12.x
Livewire 3.x
Flux components

Installation

1. Install the package via Composer

composer require scriptoshi/livewire-2fa

2. (optional) If you need to customize, publish the assets

php artisan vendor:publish --provider="Scriptoshi\Livewire2fa\TwoFactorAuthServiceProvider" --tag="config"
php artisan vendor:publish --provider="Scriptoshi\Livewire2fa\TwoFactorAuthServiceProvider" --tag="views"
php artisan vendor:publish --provider="Scriptoshi\Livewire2fa\TwoFactorAuthServiceProvider" --tag="migrations"

3. Run the migrations

This will add the required columns to your users table.

php artisan migrate

4. Include the TwoFactorAuthenticatable trait in your User model

use Scriptoshi\Livewire2fa\Traits\TwoFactorAuthenticatable;

class User extends Authenticatable
{
    use TwoFactorAuthenticatable;

    // ...
}

Configuration

The package comes with sensible defaults, but you can customize it using the corresponding .env variables. Add the following lines to your .env to customise the config

# Enable or disable 2FA functionality entirely
TWO_FACTOR_AUTH_ENABLED=true
# Require users to confirm their 2FA setup with a code
TWO_FACTOR_AUTH_CONFIRM=true
# How many OTP codes will be accepted (time window)
TWO_FACTOR_AUTH_WINDOW=1
# Number of recovery codes to generate
TWO_FACTOR_AUTH_RECOVERY_CODE_COUNT=8
# Timeout for 2FA verification (in seconds, default 15 minutes)
TWO_FACTOR_AUTH_TIMEOUT=600

Basic Usage

Adding 2FA Management to User Profile

Add the Livewire component to your user profile page:

<livewire:two-factor-management />

On Laravel 12 Starter kit:

Edit resources/views/components/settings/layout.blade.php and add:

<flux:navlist>
    <flux:navlist.item :href="route('settings.profile')" wire:navigate>{{ __('Profile') }}</flux:navlist.item>
    <flux:navlist.item :href="route('settings.password')" wire:navigate>{{ __('Password') }}</flux:navlist.item>
    <flux:navlist.item :href="route('settings.appearance')" wire:navigate>{{ __('Appearance') }}</flux:navlist.item>
    <!--Add two factor-->
    <flux:navlist.item :href="route('settings.twofactor')" wire:navigate>{{ __('Two factor Auth') }}</flux:navlist.item>
</flux:navlist>

Create the two factor auth view: resources/views/livewire/settings/twofactor.blade.php

<?php
use Livewire\Volt\Component;

new class extends Component {

}; ?>

<section class="w-full">
    @include('partials.settings-heading')
    <x-settings.layout :heading="__('Two Factor Auth')" :subheading="__('Manage two factor authentication')">
        <livewire:two-factor-management />
    </x-settings.layout>
</section>

Add the route to routes/web.php:

Volt::route('settings/twofactor', 'settings.twofactor')->name('settings.twofactor');

Integrating with Login (Laravel 12 Starter Kit)

The easiest way to integrate 2FA with Laravel 12's Livewire login is by adding the WithTwoFactorAuthentication trait directly to your login component:

Update your resources/views/livewire/auth/login.blade.php Volt component:

<?php

use Scriptoshi\Livewire2fa\Traits\WithTwoFactorAuthentication;

new #[Layout('components.layouts.auth')] class extends Component {
    use WithTwoFactorAuthentication; // add this line

   ..... rest of the code

}; ?>

update the Login method on the form submit from wire:submit="login" to wire:submit="twoFactorLogin"

<form wire:submit="twoFactorLogin">.... rest of the form</form>

Include the 2FA Modal after the form closing tag.

 </form>  <!-- Form -->
    <!-- Include the 2FA Modal -->
    <x-two-factor-auth-modal />

That's it! The login component will now:

Attempt normal login with email/password
Check if the user has 2FA enabled
If 2FA is enabled, show the 2FA modal for code verification
Complete the login process after successful 2FA verification

Using Confirmation Modals

For sensitive actions in your application, you can require password or 2FA verification:

Password Confirmation Modal

Wrap the sensitive action in your component:

<x-confirms-password wire:then="enableAdminMode">
    <flux:button type="button" wire:loading.attr="disabled">
        {{ __('Enable') }}
    </flux:button>
</x-confirms-password>

Include the trait in your Livewire component:

use Scriptoshi\Livewire2fa\Traits\ConfirmsPasswords;

class AdminForm extends Component
{
    use ConfirmsPasswords;

    public function enableAdminMode(): void
    {
        $this->ensurePasswordIsConfirmed();
        // Action logic here
    }
}

Two-Factor Confirmation Modal

For even higher security, you can require 2FA confirmation for critical operations:

Include the modal component in your template:

<x-confirms-2fa wire:then="enableAdminMode">
    <flux:button type="button" wire:loading.attr="disabled">
        {{ __('Perform Critical Action') }}
    </flux:button>
</x-confirms-2fa>

Include the trait in your Livewire component:

use Scriptoshi\Livewire2fa\Traits\ConfirmsTwoFactor;

class TwoFactorAuthenticationForm extends Component
{
    use ConfirmsTwoFactor;

    public function enableAdminMode(): void
    {
        $this->ensureTwoFactorIsConfirmed();
        // Action logic here
    }
}

Customization

Views

Customize the views by publishing them and modifying as needed:

php artisan vendor:publish --provider="Scriptoshi\Livewire2fa\TwoFactorAuthServiceProvider" --tag="views"

This will publish the views to resources/views/vendor/two-factor-auth/.

Styling

The components use Flux components and support dark mode out of the box. You can customize the appearance by:

Publishing the views (as shown above)
Modifying the Flux component usage or class attributes
For more extensive customization, you can extend or override the Livewire components

Using the Facade Directly

You can use the TwoFactorAuth facade directly for advanced use cases:

use Scriptoshi\Livewire2fa\Facades\TwoFactorAuth;

// Generate a secret key
$secret = TwoFactorAuth::generateSecretKey();

// Verify a code
$valid = TwoFactorAuth::verify($secret, $code);

// Generate QR code SVG
$svg = TwoFactorAuth::generateQrCodeSvg($appName, $email, $secret);

License

This package is open-sourced software licensed under the MIT license.

scriptoshi / livewire-2fa

Maintainers

Details