Download the PHP package ongudidan/laravel-multi-2fa without Composer

Laravel Multi-Method Two-Factor Authentication (ongudidan/laravel-multi-2fa)

A complete, production-ready Two-Factor Authentication (2FA) package for Laravel applications supporting Inertia.js (Vue/React), Blade (Livewire/Alpine/HTML), and Headless JSON APIs.

This package provides a unified layer handling all three modern 2FA channels:

1. Passkeys (WebAuthn / FIDO2): Fast, passwordless biometric authentication (Touch ID, Face ID, YubiKey, Windows Hello).
2. Authenticator App (TOTP): Industry-standard 6-digit codes generated by Google Authenticator, Authy, Microsoft Authenticator, 1Password, etc.
3. Email OTP: Single-use, timed 6-digit verification codes sent directly to the user's registered email address.
4. Smart Login Challenge Selection: Automatically detects active methods per user and prompts them with a verification method selection screen when multiple channels are available.

🎨 Supported Frontend Stacks

• Inertia.js (Vue 3 / React): Full UI components with reactive state, pin inputs, and modal management.
• Blade (Vanilla / Alpine.js / Livewire): Built-in responsive HTML & Tailwind views out-of-the-box, with embedded vanilla JavaScript for WebAuthn passkeys (no npm build required!).
• Headless API (Mobile / SPAs): Automatic JSON responses when Accept: application/json is requested.

Requirements

• PHP ^8.2
• Laravel Framework ^11.0 or ^12.0
• laravel/fortify ^1.20 or ^1.30
• laravel/passkeys ^0.1 or ^0.2

🤖 AI Agent Implementation Prompt

When integrating this package into any new or existing Laravel project (Inertia or Blade), copy and paste this concise prompt directly into your AI coding assistant (Antigravity, Cursor, Claude Code, Copilot, or ChatGPT):

Setup & Integration Guide

Step 1: Install Package & Dependencies

If developing locally or using a path repository, register packages/ongudidan/laravel-multi-2fa in your composer.json repositories first:

Install the package via Composer:

If using Inertia.js (Vue/React):

(Blade projects do not require @laravel/passkeys because built-in vanilla WebAuthn scripts are included).

Step 2: Publish Assets & Run Migrations

1. Publish the configuration:

2. Publish UI views based on your stack:

   • For Inertia.js (Vue 3):

   (Publishes EmailOtpLogin.vue, LoginChallengeSelection.vue, TwoFactor.vue, Passkeys.vue)

• For Blade:

  (Optional: Blade views work out-of-the-box without publishing, but publishing allows you to customize the templates in resources/views/vendor/multi-2fa/)

3. Run migrations:

Step 3: Configure User Model

In app/Models/User.php, implement PasskeyUser and attach the 2FA traits:

Step 4: Configure Fortify Pipeline

In app/Providers/FortifyServiceProvider.php, plug the package's pipeline actions into Fortify::authenticateThrough:

Step 5: Share Security Settings in Inertia (Inertia Projects Only)

In app/Http/Middleware/HandleInertiaRequests.php, share the security settings with your frontend components:

Step 6: Route Protection Middleware (Optional)

To prevent users from navigating to two-factor configuration routes when globally disabled in system settings:

In your routing bootstrap (bootstrap/app.php in Laravel 11/12):

Configuration (config/multi-2fa.php)

How It Works at Runtime

1. User enters email & password on /login.
2. RedirectIfEmailOtpRequired validates credentials and queries TwoFactorService::getAvailableMethodsForUser($user).
3. Smart Routing:
   • Multiple methods available (e.g. user has Passkey + Email OTP, or Authenticator + Email OTP):
     • User is redirected to /login-challenge-selection to pick their preferred method.
   • Only Email OTP available:
     • Code is generated, emailed, and user is redirected directly to /email-otp-login.
   • Only Authenticator App active:
     • Pipeline falls through to RedirectIfTwoFactorAuthenticatable which redirects to /two-factor-challenge.
   • No 2FA configured for this user:
     • Normal login completes instantly without prompts.
4. Method Switching:
   • While on the Email OTP or Authenticator screens, if the user has alternate methods, a "← Choose a different verification method" option is shown allowing seamless switching.

License

The MIT License (MIT). Developed by Ongudidan.