Download the PHP package mustafa-awami/lara2fa without Composer

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

• 🚀 Features
• 📝 Prerequisites
• 🧰 Installation
• ⚙️ Set Up
  • Step 1️⃣: Install & Publish
  • Step 2️⃣: User Model
  • Step 3️⃣: Routes
  • Step 4️⃣: Fortify Config
  • Step 5️⃣: Migrate & Build
• 🧪 Example Repository
• 💻 Usage
• 🛠️ Configuration (Optional)
  • Two-Factor Authentication
  • Authenticator App (TOTP)
  • Email (OTP)
  • Passkeys
  • Recovery Codes
  • Routes
  • Rate Limiter
• 🚑 Troubleshooting & Important Notes
  • ⚠️ Warning: File Overwrites
  • Passkey Requirements
• 👥 Contributing
• 🔒 Security Vulnerabilities
• ⚖️ License
• 💖 Support

🚀 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

• 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

Install via Composer:

⚙️ Set Up

Step 1️⃣: Install & Publish

After installing via composer, publish resources using the lara2fa:install Artisan command

During installation, you’ll be asked which starter kit/stack you are currently using:

• 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:

Depending on the selected methods, the published lara2fa.php config file will be updated to enable the selected methods and disable the rest.

⚠️ Warning

This instalation process may override some of your files in your project directory, see the full list of files at the Troubleshooting Section

Step 2️⃣: User Model

In User.php model, replace:

with:

Step 3️⃣: Routes

In settings.php route file, replace:

with:

Step 4️⃣: Fortify Config

In fortify.php config file, disable the two-factor feature by commenting it out like so:

Step 5️⃣: Migrate & Build

Run the migrations to create the new tables:

Finally, run the build command:

🧪 Example Repository

You will find an example of usage on Mustafa-Awami/lara2fa-example.

💻 Usage

Users can enable any of the two-factor methods in thier settings page.

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.

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).

🛠️ Configuration (Optional)

Two-Factor Authentication

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)

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

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

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

If you want to customize the lara2fa.php route file, first publish it with the following command:

Then, in routes/web.php, add the following line at the end:

Make sure to disable the original route file by adding Lara2fa::ignoreRoutes(); in the register method of app/Providers/Lara2faServiceProvider.php:

Here is the list of defined routes:

You can customize the first part of the URL by setting the prefix value in the lara2fa.php config file.

Rate Limiter

Lara2fa defines 3 rate limiters:

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)

• 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)

• 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.

You can also view them inside the limiters value in the lara2fa.php config file.

🚑 Troubleshooting & Important Notes

⚠️ 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

For Passkeys to work correctly, the following conditions must be met:

• Use a browser that supports WebAuthn (see: https://caniuse.com/webauthn).
• 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 to serve your sites over HTTPS).

👥 Contributing

Thank you for considering contributing to Lara2fa! You can read the contribution guide.

🔒 Security Vulnerabilities

Please review the security policy on how to report security vulnerabilities.

⚖️ License

The Lara2FA package is licensed under the MIT license.

💖 Support

If you find this package helpful, please consider sponsoring the project to support its development and maintenance!