PHPackages mustafa-awami/lara2fa - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Authentication & Authorization](/categories/authentication) 4. / 5. mustafa-awami/lara2fa ActiveLibrary[Authentication & Authorization](/categories/authentication) mustafa-awami/lara2fa ===================== Laravel 2FA package with TOTP, Email OTP, Passkeys & Recovery Codes. v1.0.0(5mo ago)8191MITPHPPHP ^8.2CI passing Since Nov 27Pushed 5mo agoCompare [ Source](https://github.com/Mustafa-Awami/Lara2fa)[ Packagist](https://packagist.org/packages/mustafa-awami/lara2fa)[ GitHub Sponsors](https://github.com/Mustafa-Awami)[ RSS](/packages/mustafa-awami-lara2fa/feed)WikiDiscussions master Synced 1mo ago READMEChangelogDependencies (5)Versions (2)Used By (0) [![Logo Lara2fa](/art/logo.png)](/art/logo.png) [![Build Status](https://github.com/Mustafa-Awami/Lara2fa/actions/workflows/tests.yml/badge.svg)](https://github.com/Mustafa-Awami/Lara2fa/actions)[![Linter Status](https://github.com/Mustafa-Awami/Lara2fa/actions/workflows/lint.yml/badge.svg)](https://github.com/Mustafa-Awami/Lara2fa/actions)[![Latest Stable Version](https://camo.githubusercontent.com/13f307241b5b60966560f3d30d21376adbc8673f9054ec6880b0ee156ea93ad5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d7573746166612d6177616d692f6c617261326661)](https://packagist.org/packages/mustafa-awami/lara2fa)[![Total Downloads](https://camo.githubusercontent.com/90838775d73ab77f6e5c3b1411293ca06ad839e191ad58726a69f0887773b967/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d7573746166612d6177616d692f6c617261326661)](https://packagist.org/packages/mustafa-awami/lara2fa)[![License](https://camo.githubusercontent.com/e24406f1c746247925fc24695cae152549a6e9de96e2352a745fad44f170775f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6d7573746166612d6177616d692f6c617261326661)](https://packagist.org/packages/mustafa-awami/lara2fa)[![Laravel 12+](https://camo.githubusercontent.com/e674224f761b399fcb611ae556a00a23c05f0db9666478556516e02c473d15f1/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31322532422d7265643f6c6f676f3d6c61726176656c)](https://laravel.com/) **Lara2FA** is a modern, flexible, and developer-friendly **Two-Factor Authentication (2FA)** package for Laravel. It supports **powerful authentication methods** out of the box: - βœ‰οΈ **Email OTP** - πŸ”’ **Authenticator Apps (TOTP)** - πŸͺͺ **WebAuthn (Passkeys / Security Keys / Biometrics)** - πŸ”‘ **Recovery Codes** Designed for simplicity, security, and seamless integration into any Laravel project. --- πŸ“œ Table of Contents =================== [](#-table-of-contents) - [πŸš€ Features](#-features) - [πŸ“ Prerequisites](#-prerequisites) - [🧰 Installation](#-installation) - [βš™οΈ Set Up](#%EF%B8%8F-set-up) - [Step 1️⃣: Install & Publish](#step-1%EF%B8%8F%E2%83%A3-install--publish) - [Step 2️⃣: User Model](#step-2%EF%B8%8F%E2%83%A3-user-model) - [Step 3️⃣: Routes](#step-3%EF%B8%8F%E2%83%A3-routes) - [Step 4️⃣: Fortify Config](#step-4%EF%B8%8F%E2%83%A3-fortify-config) - [Step 5️⃣: Migrate & Build](#step-5%EF%B8%8F%E2%83%A3-migrate--build) - [πŸ§ͺ Example Repository](#-example-repository) - [πŸ’» Usage](#-usage) - [πŸ› οΈ Configuration (Optional)](#%EF%B8%8F-configuration-optional) - [Two-Factor Authentication](#two-factor-authentication) - [Authenticator App (TOTP)](#1--authenticator-app-totp) - [Email (OTP)](#2--email-otp) - [Passkeys](#3--passkeys) - [Recovery Codes](#4--recovery-codes) - [Routes](#routes) - [Rate Limiter](#rate-limiter) - [πŸš‘ Troubleshooting & Important Notes](#-troubleshooting--important-notes) - [⚠️ Warning: File Overwrites](#%EF%B8%8F-warning-file-overwrites) - [Passkey Requirements](#passkey-requirements) - [πŸ‘₯ Contributing](#-contributing) - [πŸ”’ Security Vulnerabilities](#-security-vulnerabilities) - [βš–οΈ License](#%EF%B8%8F-license) - [πŸ’– Support](#-support) --- πŸš€ Features ========== [](#-features) - πŸ”’ Compatible with Google Authenticator, Authy, and 1Password - βœ‰οΈ Built-in Email OTP - πŸͺͺ WebAuthn support for FIDO2 devices, Windows Hello, Touch ID, and Passkeys - 🧩 Easy install command with feature selection - πŸ”’ Secure and standards-compliant implementation - πŸ§‘β€πŸ’» Developer Friendly – clean, easy setup, and customizable flows --- πŸ“ Prerequisites =============== [](#-prerequisites) - **Laravel Framework:** 12.37.0+ - **Laravel Fortify:** 1.32.0+ - **Frontend Stack:** The installer currently supports **Inertia** with **React** or **Vue**, **Livewire** can be added if requested. --- 🧰 Installation ============== [](#-installation) Install via Composer: ``` composer require mustafa-awami/lara2fa -W ``` --- βš™οΈ Set Up ========= [](#️-set-up) Step 1️⃣: Install & Publish ------------------------------- [](#step-1️⃣-install--publish) After installing via composer, publish resources using the `lara2fa:install` Artisan command ``` php artisan lara2fa:install ``` During installation, you’ll be asked which starter kit/stack you are currently using: ``` Which stack are you using? [1] react [2] vue ``` - **Note:** Currently supported stacks are React and Vue only. Livewire can be added if requested. Then you will be asked which of the following 2FA methods would you like to enable: ``` Which 2FA methods would you like to enable? (comma separated): [1] Authenticator App (TOTP) [2] Email OTP [3] Passkeys [4] All of the above ``` Depending on the selected methods, the published `lara2fa.php` config file will be updated to enable the selected methods and disable the rest. ### ⚠️ Warning [](#️-warning) This instalation process may override some of your files in your project directory, see the full list of files at the [Troubleshooting Section](#-troubleshooting--important-notes) Step 2️⃣: User Model -------------------- [](#step-2️⃣-user-model) In `User.php` model, replace: ``` use Laravel\Fortify\TwoFactorAuthenticatable; ``` with: ``` use MustafaAwami\Lara2fa\Traits\TwoFactorAuthenticatable; ``` Step 3️⃣: Routes ---------------- [](#step-3️⃣-routes) In `settings.php` route file, replace: ``` use App\Http\Controllers\Settings\TwoFactorAuthenticationController; ``` with: ``` use MustafaAwami\Lara2fa\Http\Controllers\Settings\TwoFactorAuthenticationController; ``` Step 4️⃣: Fortify Config ------------------------ [](#step-4️⃣-fortify-config) In `fortify.php` config file, disable the two-factor feature by commenting it out like so: ``` // Features::twoFactorAuthentication([ // 'confirm' => true, // 'confirmPassword' => true, // // 'window' => 0, // ]), ``` Step 5️⃣: Migrate & Build ----------------------------- [](#step-5️⃣-migrate--build) Run the migrations to create the new tables: ``` php artisan migrate ``` Finally, run the build command: ``` npm run build ``` --- πŸ§ͺ Example Repository ==================== [](#-example-repository) You will find an example of usage on [Mustafa-Awami/lara2fa-example](https://github.com/Mustafa-Awami/lara2fa-example). --- πŸ’» Usage ======= [](#-usage) Users can enable any of the two-factor methods in thier settings page. [![two-factor-settings](/art/two-factor-settings.png)](/art/two-factor-settings.png) By enabling any of the main 3 methods, recovery codes will be enabled automaticly. Users who have enabled any of the two-factor methods will be automatically redirected to the two-factor-challenge page after entering their password. [![two-factor-challenge](/art/two-factor-challenge.png)](/art/two-factor-challenge.png) If a user enabled passkeys, they can login directly without entering their password in the login page by clicking on the `Use Passkey` button (passwordless authentication). [![login](/art/login.png)](/art/login.png) --- πŸ› οΈ Configuration (Optional) =========================== [](#️-configuration-optional) Two-Factor Authentication ------------------------- [](#two-factor-authentication) ### 1- Authenticator App (TOTP) [](#1--authenticator-app-totp) This section configures Two-Factor Authentication (2FA) using a time-based one-time password (TOTP) app like Google Authenticator or Authy. You will find the configuration for this feature in `lara2fa.php` config file under `Features:authenticatorAppTwoFactorAuthentication([...])`. - `'enable' => true`: Enable or disable this feature. - `'confirm' => true`: Requires users to confirm setup by entering a code from their app. - `'confirmPassword' => true`: Requires users to re-enter their password before enabling or modifying this feature. - `'window' => 1`: Allows a 1-minute grace period for time differences (clock drift) between the user's device and the server. - `'secret-length' => 16`: The length of the secret key generated for the authenticator app. ### 2- Email (OTP) [](#2--email-otp) This configures 2FA by sending a one-time code to the user's registered email address. You will find the configuration for this feature in `lara2fa.php` config file under `Features:emailTwoFactorAuthentication([...])`. - `'enable' => true`: Enable or disable this feature. - `'confirm' => true`: Requires a confirmation step during setup. - `'confirmPassword' => true`: Requires users to re-enter their password before enabling or modifying this feature. - `'window' => 10`: The time (in minutes) for which the email verification code is valid. ### 3- Passkeys [](#3--passkeys) This configures login using device-based security like Face ID, Touch ID, Windows Hello, or physical security keys (YubiKey). It can also be used as passwordless authentication. You will find the configuration for this feature in `lara2fa.php` config file under `Features:passkeys([...])`. - `'enable' => true`: Enable or disable this feature. - `'max_passkeys' => 3`: The maximum number of Passkeys a user can have. - `'confirmPassword' => true`: Requires users to re-enter their password to add or remove passkeys. - `'authentication_mode' => 'both'`: Allows passkeys to be used for both single-factor (passwordless) and two-factor (password + passkey) authentication. - `'challenge_length' => 32`: The length of the random string used in the authentication challenge. - `'timeout' => 60000`: Time (in ms) that the caller is willing to wait for the call to complete. - `'icon' => env('PASSKEY_ICON')`: URL which resolves to an image associated with the entity. - `'attestation_conveyance' => 'none'`: This parameter specify the preference regarding the attestation conveyance during credential generation. - `'attachment_mode' => null`: Authentication can be tied to the current device or a cross-platform device or buth. - `'user_verification' => 'preferred'`: Most authenticators and smartphones will ask the user to actively verify themselves for log in. Use "required" to always ask verify, "preferred" to ask when possible, and "discouraged" to just ask for user presence. - `'resident_key' => 'preferred'`: By default, users must input their email to receive a list of credentials ID to use for authentication, but they can also login without specifying one if the device can remember them, allowing for true one-touch login. If required or preferred, login verification will be always required. ### 4- Recovery Codes [](#4--recovery-codes) This configures one-time-use backup codes for users who lose access to their 2FA device. You will find the configuration for this feature in `lara2fa.php` config file under `Features:recoveryCodes([...])`. - `'enable' => true`: Enable or disable this feature. - `'confirmPassword' => true`: Requires users to re-enter their password to view or generate new codes. - `'requireTwoFactorAuthenticationEnabled' => true`: Require a Two-Factor Authentication method to be enabled before allowing recovery code generation. - `'numberOfCodesGenerated' => 8`: The total number of unique recovery codes that will be generated for the user. Routes ------ [](#routes) If you want to customize the `lara2fa.php` route file, first publish it with the following command: ``` php artisan vendor:publish --tag=lara2fa-routes ``` Then, in `routes/web.php`, add the following line at the end: ``` require __DIR__.'/lara2fa.php'; ``` Make sure to disable the original route file by adding `Lara2fa::ignoreRoutes();` in the register method of `app/Providers/Lara2faServiceProvider.php`: ``` namespace App\Providers; use MustafaAwami\Lara2fa\Lara2fa; class Lara2faServiceProvider extends ServiceProvider { public function register(): void { Lara2fa::ignoreRoutes(); } } ``` Here is the list of defined routes: RequestRoute NameDescriptionGET `/two-factor-challenge``two-factor.login`Show the two-factor authentication challenge view.POST `/two-factor-challenge`-Submitting the two-factor authentication challenge form.POST `/settings/authenticator-app-two-factor-authentication``authenticator-app-two-factor.enable`Enable authenticator-app two-factor authentication for the authenticated user.POST `/settings/confirmed-authenticator-app-two-factor-authentication``authenticator-app-two-factor.confirm`Confirm authenticator-app two-factor authentication for the authenticated user.DELETE `/settings/authenticator-app-two-factor-authentication``authenticator-app-two-factor.disable`Disable authenticator-app two-factor authentication for the authenticated user.GET `/settings/authenticator-app-two-factor-qr-code``authenticator-app-two-factor.qr-code`Get the SVG element for the user's two-factor authentication QR code.GET `/settings/authenticator-app-two-factor-secret-key``authenticator-app-two-factor.secret-key`Get the current user's two-factor authentication setup / secret key.POST `/settings/email-two-factor-authentication``email-two-factor.enable`Enable email two-factor authentication for the authenticated user.POST `/settings/confirmed-email-two-factor-authentication``email-two-factor.confirm`Confirm email two-factor authentication for the authenticated user.DELETE `/settings/email-two-factor-authentication``email-two-factor.disable`Disable email two-factor authentication for the authenticated user.POST `/settings/email-two-factor-authentication-send-code``email-two-factor.send-code`Send the OTP via email.GET `/settings/passkeys-two-factor-authentication``passkeys-two-factor.get`Get the user's passkeys.GET `/settings/passkeys-two-factor-authentication-registerOptions``passkeys-two-factor.getRegisterOptions`Get passkey registration options.POST `/settings/passkeys-two-factor-authentication``passkeys-two-factor.store`Create a new passkey for the authenticated user.DELETE `/settings/passkeys-two-factor-authentication``passkeys-two-factor.disable`Delete all passkeys for the authenticated user.DELETE `/settings/passkeys-two-factor-authentication/{passkey}/destroy``passkeys-two-factor.destroy`Delete the provided passkey for the authenticated user.PUT `/settings/passkeys-two-factor-authentication/{passkey}/update``passkeys-two-factor.update`Update the name of the provided passkey for the authenticated user.GET `/settings/two-factor-recovery-codes``two-factor-recovery-codes.get`Get the two-factor authentication recovery codes for the authenticated user.POST `/settings/two-factor-recovery-codes``two-factor-recovery-codes.generate`Generate a fresh set of two-factor authentication recovery codes.DELETE `/settings/two-factor-recovery-codes``two-factor-recovery-codes.disable`Delete the two-factor authentication recovery codes for the authenticated user.GET `/passkeys-two-factor/authenticateOptions``passkeys-two-factor.authenticateOptions`Get passkey authentication options.POST `/passkeys-two-factor/authenticate``passkeys-two-factor.authenticate`Authenticate the user with the given passkey.You can customize the first part of the URL by setting the `prefix` value in the `lara2fa.php` config file. Rate Limiter ------------ [](#rate-limiter) Lara2fa defines 3 rate limiters: ### 1- Passkey Login Attempts (passkey-login) [](#1--passkey-login-attempts-passkey-login) - This limiter protects the initial login/passkey verification endpoint. - Purpose: Prevents rapid, repeated login attempts (brute-force) from a single user and/or IP address. - Limit: 5 attempts per minute. ### 2- Two-Factor Email Notification (two-factor-email-notify) [](#2--two-factor-email-notification-two-factor-email-notify) - This limiter controls the "resend 2FA code" feature. - Purpose: Prevents a user from spamming the system to send dozens of 2FA emails, which could abuse a mail service. - Limit: 2 attempts per minute. ### 3- Two-Factor Code Verification (two-factor-login) [](#3--two-factor-code-verification-two-factor-login) - This limiter protects the endpoint where the user submits their 2FA code. - Purpose: Prevents a user from rapidly guessing the 6-digit (or similar) 2FA code. - Limit: 5 attempts per minute. You can find and customize the rate limiters inside the `boot` method of `\app\Providers\Lara2faServiceProvider.php`. ``` namespace App\Providers; use Illuminate\Support\Str; use Illuminate\Http\Request; use Laravel\Fortify\Fortify; use Illuminate\Support\ServiceProvider; use Illuminate\Cache\RateLimiting\Limit; use Illuminate\Support\Facades\RateLimiter; use Illuminate\Validation\ValidationException; class Lara2faServiceProvider extends ServiceProvider { public function boot(): void { RateLimiter::for('passkey-login', function (Request $request) { $throttleKey = Str::transliterate(Str::lower($request->input(Fortify::username())).'|'.$request->ip()); return Limit::perMinute(5)->by($throttleKey)->response(function (Request $request,array $headers) { $seconds = $headers['Retry-After']; throw ValidationException::withMessages([ Fortify::username() => [__('Too many attempts. Please try again after') . $seconds. __(' seconds')], ]); }); }); RateLimiter::for('two-factor-email-notify', function (Request $request) { $throttleKey = $request->session()->get('login.id'); return Limit::perMinute(2)->by($throttleKey)->response(function (Request $request,array $headers) { $seconds = $headers['Retry-After']; throw ValidationException::withMessages([ 'attempts' => [__('Too many attempts. Please try again after ') . $seconds. __(' seconds')], ])->errorBag('EmailTwoFactorAuthenticationNotification'); }); }); RateLimiter::for('two-factor-login', function (Request $request) { $throttleKey = $request->session()->get('login.id'); return Limit::perMinute(5)->by($throttleKey)->response(function (Request $request,array $headers) { $seconds = $headers['Retry-After']; throw ValidationException::withMessages([ 'attempts' => [__('Too many attempts. Please try again after ') . $seconds. __(' seconds')], ]); }); }); } } ``` You can also view them inside the `limiters` value in the `lara2fa.php` config file. --- πŸš‘ Troubleshooting & Important Notes ======================================= [](#-troubleshooting--important-notes) ⚠️ Warning: File Overwrites --------------------------- [](#️-warning-file-overwrites) The installation process may publish files that overwrite existing files in your project (for example, configuration or resource files). It’s strongly recommended to commit your changes or back up your project before running the install command. Here is the list of files that will be published: - `config/lara2fa.php` - `database/migrations/2024_07_29_090549_add_two_factor_email_columns_to_users_table.php` - `database/migrations/2025_09_10_081543_create_passkeys_table.php` - `app/Providers/Lara2faServiceProvider.php` - `app/Providers/FortifyServiceProvider.php` - `tests/Feature/Auth/AuthenticationTest.php` - `tests/Feature/Auth/TwoFactorChallengeTest.php` - `tests/Feature/Settings/TwoFactorAuthenticationTest.php` Here are the React resource files that will be published if React is chosen: - `resources/js/pages/settings/two-factor.tsx` - `resources/js/pages/auth/login.tsx` - `resources/js/pages/auth/two-factor-challenge.tsx` - `resources/js/components/confirm-password-dialog.tsx` Here are the Vue stack files that will be published if Vue is chosen: - `resources/js/pages/settings/TwoFactor.vue` - `resources/js/components/TwoFactorAuthenticatorApp.vue` - `resources/js/components/TwoFactorEmail.vue` - `resources/js/components/TwoFactorPasskeys.vue` - `resources/js/components/TwoFactorRecoveryCodes.vue` - `resources/js/pages/auth/Login.vue` - `resources/js/pages/auth/TwoFactorChallenge.vue` - `resources/js/components/ConfirmPasswordDialog.vue` Passkey Requirements -------------------- [](#passkey-requirements) For Passkeys to work correctly, the following conditions must be met: - Use a browser that supports WebAuthn (see: ). - A proper domain (localhost and 127.0.0.1 will be rejected by webauthn.js). - An SSL/TLS certificate trusted by your browser (self-signed is okay). - An HTTPS connection on port 443 (ports other than 443 will be rejected) (use [Laravel Herd](https://herd.laravel.com/) to serve your sites over HTTPS). --- πŸ‘₯ Contributing ============== [](#-contributing) Thank you for considering contributing to Lara2fa! You can read the [contribution guide](.github/CONTRIBUTING.md). --- πŸ”’ Security Vulnerabilities ========================== [](#-security-vulnerabilities) Please review the [security policy](.github/SECURITY.md) on how to report security vulnerabilities. --- βš–οΈ License ========== [](#️-license) The Lara2FA package is licensed under the **[MIT license](/LICENSE.md)**. --- πŸ’– Support ========= [](#-support) If you find this package helpful, please consider sponsoring the project to support its development and maintenance! [ ![Sponsor](https://camo.githubusercontent.com/dd15d25b666bd45a1af4201312dc192a591c3f8ab47690524ff92fd2904670da/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53706f6e736f722d4d7573746166612532304177616d692d70696e6b3f7374796c653d666f722d7468652d6261646765266c6f676f3d6769746875622d73706f6e736f7273)](https://github.com/sponsors/Mustafa-Awami) ### Health Score 38 β€” LowBetter than 85% of packages Maintenance72 Regular maintenance activity Popularity18 Limited adoption so far Community6 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits β€” single point of failure How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 165d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/90f1f9a8e8ed7fff1131645d818595f1eb771223ff86f40f272792a29cac2696?d=identicon)[Mustafa-Awami](/maintainers/Mustafa-Awami) --- Top Contributors [![Mustafa-Awami](https://avatars.githubusercontent.com/u/36249421?v=4)](https://github.com/Mustafa-Awami "Mustafa-Awami (83 commits)") --- Tags 2faauthenticator-appfido2laravellaravel-packageotppasskeyssecuritytotptwo-factortwo-factor-authenticationwebauthnlaravelgoogle authenticatorotptotpsecurityauthAuthentication2faTwo Factor Authenticationlaravel-packagelaravel-plugintwo-factorLaravel SecurityFIDO2webauthnauth packageMFApasskeystfaMulti Factor Authenticationotp verificationemail-otpu2ftwo-step verificationauthenticator applogin securitylaravel addon ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/mustafa-awami-lara2fa/health.svg) ``` [![Health](https://phpackages.com/badges/mustafa-awami-lara2fa/health.svg)](https://phpackages.com/packages/mustafa-awami-lara2fa) ``` ### Alternatives [remotemerge/totp-php Lightweight, fast, and secure TOTP (2FA) authentication library for PHP β€” battle tested, dependency free, and ready for enterprise integration. 2010.2k](/packages/remotemerge-totp-php)[paragonie/multi-factor Vendor-agnostic two-factor authentication library 142195.5k2](/packages/paragonie-multi-factor)[ellaisys/aws-cognito AWS Cognito package that allows Auth and other related features using the AWS SDK for PHP 120220.7k1](/packages/ellaisys-aws-cognito)[sicaboy/laravel-mfa A Laravel package of Multi-factor Authentication (MFA/2FA) with a middleware. 101.2k](/packages/sicaboy-laravel-mfa) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)