Download the PHP package jmrashed/two-factor-auth without Composer

Laravel Two-Factor Authentication (2FA)

Overview

The Laravel Two-Factor Authentication (2FA) package provides a seamless way to enhance the security of Laravel applications by implementing two-factor authentication for user authentication. With support for multiple authentication methods and customizable configuration options, this package offers developers a robust solution to protect user accounts against unauthorized access.

Key Features

• Multiple 2FA Methods: Supports various two-factor authentication methods, including SMS, email, TOTP (Time-Based One-Time Password), and more.

• Customizable Configuration: Allows developers to configure 2FA settings according to their application's requirements, including enabling/disabling specific authentication methods, setting up recovery options, and defining access policies.

• Seamless Integration: Integrates seamlessly with Laravel's authentication system, making it easy to add two-factor authentication to existing Laravel applications without extensive modifications.

• User-Friendly Interfaces: Provides intuitive user interfaces for enabling, disabling, and managing two-factor authentication settings, ensuring a smooth user experience for account security management.

• Comprehensive Documentation: Offers comprehensive documentation with installation instructions, usage guidelines, configuration options, and best practices for implementing and managing two-factor authentication in Laravel applications.

Why Use Laravel 2FA

• Enhanced Security: Protects user accounts against common security threats such as password breaches, phishing attacks, and unauthorized access attempts.

• Compliance Requirements: Helps meet compliance requirements for securing sensitive user data and ensuring regulatory compliance in various industries.

• User Trust and Confidence: Builds trust and confidence among users by providing an additional layer of security for their accounts, leading to increased user satisfaction and loyalty.

Getting Started

To get started with Laravel 2FA, simply install the package via Composer and follow the installation and configuration instructions provided in the documentation. With just a few simple steps, you can enhance the security of your Laravel applications and provide users with peace of mind knowing their accounts are well-protected.

Requirements

• PHP >= 8.1
• Laravel >= 10.x
• Composer (for package installation)

Ensure that your server environment meets the following requirements:

• PHP Version: The package requires PHP version 8.1 or later to run properly. You can check your PHP version by running php -v in your terminal.

• Laravel Version: The package is compatible with Laravel version 10.x or later. Make sure your Laravel application is using the specified version or later for seamless integration.

• Composer: Composer is required to install the package and manage its dependencies. If you haven't installed Composer yet, you can download and install it from composer.

Before proceeding with the installation, verify that your server environment meets these requirements to ensure compatibility and smooth operation of the two-factor authentication package.

Installation

You can install the Laravel Two-Factor Authentication (2FA) package via Composer by running the following command in your terminal:

After installing the package, Laravel will automatically discover the service provider. If you're using Laravel version 5.5 or higher, the package will be auto-discovered. For older versions of Laravel, you may need to manually register the service provider in your config/app.php file:

How it Works

The Laravel Two-Factor Authentication (2FA) package introduces a flexible mechanism to enhance user authentication with an additional layer of security. Here's how it functions:

1. Contract Integration

The package seamlessly integrates a contract to determine whether a user, following successful credential validation, should employ Two-Factor Authentication (2FA) as a supplementary authentication measure.

2. Custom Views and Helper Functions

Included in the package are custom views and helper functions dedicated to managing Two-Factor Authentication (2FA) during login attempts and settings management. These resources facilitate the implementation of 2FA without the need for a new guard. However, advanced users have the option to customize the authentication process manually if desired.

3. Optional Middleware

The Auth2FA login flow itself doesn't require middleware. But the package does ship two middleware aliases you can opt into for route-level protection:

• 2fa.enabled — blocks a route unless the current user has 2FA turned on.
• 2fa.confirm — asks an already-logged-in user to re-confirm with a 2FA code before reaching a sensitive route (settings, billing, etc.), remembering the confirmation in the session for a configurable time.

See docs.md for usage examples.

4. Extensibility

The package is designed to be extensible, accommodating potential future enhancements and customizations. It offers a foundation upon which users can build additional features or integrate with other parts of their Laravel application.

Setup

Step - 01

Begin by installing the necessary components into your Laravel application, including migrations, translations, views, and configuration, using the following Artisan command:

Tip:

You can customize the migration before running it, such as adding new columns or changing the table name. Refer to the migration documentation for more details.

After installation, migrate the database tables using the standard Artisan migrate command:

Step - 02

Integrate the Two-Factor Authentication features into your User model or any other model where you want to enable Two-Factor Authentication. Simply add the TwoFactorAuthenticatable contract and the TwoFactorAuthentication trait to the model as shown below:

Tip:

The TwoFactorAuthenticatable contract identifies models using Two-Factor Authentication, while the TwoFactorAuthentication trait provides convenient methods for managing Two-Factor Authentication.

That's it! Your application is now equipped to utilize Two-Factor Authentication for enhanced security.

Managing Two-Factor Authentication Methods

Users can manage their Two-Factor Authentication (2FA) methods (TOTP, SMS, Email) through a dedicated settings page.

To access the 2FA settings, navigate to the /two-factor-settings route in your application. This page allows users to:

• Enable/Disable TOTP: Generate a QR code and secret key for authenticator apps, confirm the setup, or disable TOTP.
• Enable/Disable SMS 2FA: Enter and verify a phone number, send verification codes, and enable/disable SMS authentication.
• Enable/Disable Email 2FA: Enable email-based 2FA, send verification codes to their registered email, and disable it.

Here's an example of how you might link to the settings page:

Enabling TOTP (Authenticator App)

To enable TOTP, the user needs to synchronize a Shared Secret with their Authenticator app.

Tip:

Popular free Authenticator apps include iOS Authenticator, FreeOTP, Authy, and Google Authenticator, among others.

On the 2FA settings page, when enabling TOTP, a QR code and a secret key will be displayed. The user should scan the QR code or manually enter the secret key into their authenticator app. After setting up, they will be prompted to enter a code from their app to confirm and activate TOTP.

Enabling SMS 2FA

To enable SMS 2FA, the user must provide and verify their phone number.

On the 2FA settings page, the user can enter their phone number. After saving, a verification code will be sent to the provided number. The user must then enter this code to verify their phone number and activate SMS 2FA.

Enabling Email 2FA

To enable Email 2FA, the user's registered email address will be used.

On the 2FA settings page, the user can enable Email 2FA. A verification code will be sent to their registered email address. The user must then enter this code to verify and activate Email 2FA.

Recovery Codes

Recovery Codes, used as backup authentication methods, are automatically generated each time Two-Factor Authentication is enabled. By default, a collection of ten one-use 8-character codes is created.

You can retrieve these codes using the getRecoveryCodes() method.

Ensure you provide users with their Recovery Codes after enabling Two-Factor Authentication and advise them to securely store them. The generateRecoveryCodes() method can be used to generate a fresh batch of codes, replacing the previous set.

Important:

Users should be encouraged to generate new Recovery Codes if they deplete their current set or if they become inactive.

Logging In

For seamless user authentication, utilize the Auth2FA facade provided by the package, which handles the authentication process with support for Two-Factor Authentication.

Tip:

For Laravel UI or Laravel Breeze, refer to the package documentation for specific integration instructions.

In your Login Controller, employ the Auth2FA::attempt() method with the user's credentials. If Two-Factor Authentication is required, the user will be prompted to enter their 2FA Code.

This package enables TOTP authentication using 6 digits codes. No need for external APIs.

Protecting Routes with Middleware

Beyond the login flow, use the 2fa.enabled and 2fa.confirm middleware to gate specific routes:

Validating Codes Directly

A totp validation rule is available for form requests:

Events

The package fires events you can listen for: TwoFactorEnabled, TwoFactorDisabled, TwoFactorMethodChanged, TwoFactorRecoveryCodesGenerated, TwoFactorRecoveryCodesDepleted, TwoFactorCodeSent, TwoFactorCodeFailed, and TwoFactorSafeDeviceAdded.

See docs.md for the full reference, including the SMS/Email provider abstraction, queueing code delivery, and JSON/API responses.

Authors

This package is maintained by jmrashed, a passionate developer dedicated to enhancing Laravel development experiences.

Feel free to contribute or report issues on GitHub. Your feedback and contributions are highly appreciated!

Contributing

We welcome contributions from everyone! Whether you're fixing a typo, adding a feature, or suggesting improvements, your contributions are valued and appreciated.

Follow these guidelines

If you're new to contributing to open-source projects, don't worry! Here's how you can get started:

1. Fork the repository.
2. Clone your forked repository to your local machine.
3. Create a new branch for your changes.
4. Make your changes and commit them with clear and descriptive messages.
5. Push your changes to your forked repository.
6. Submit a pull request to the main repository.

Code of Conduct

Please note that we have a Code of Conduct in place to ensure a welcoming and inclusive environment for everyone. By participating in this project, you agree to abide by its terms.

Feedback

Your feedback is crucial for the improvement of this package. If you encounter any issues, have ideas for new features, or simply want to share your thoughts, please open an issue on GitHub.

Thank you for your contributions! Together, we can make this package even better.

Documentation

Explore our comprehensive documentation to learn more about using the Two-Factor Authentication package:

• Documentation: Access detailed guides, tutorials, and API references to understand how to integrate and utilize the Two-Factor Authentication package effectively.

Our documentation is continually updated to provide you with the latest information and best practices. If you have any questions or need further assistance, don't hesitate to reach out or open an issue on GitHub. We're here to help you succeed with your authentication needs.

Author

Md Rasheduzzaman
Full-Stack Software Engineer & Technical Project Manager

Building scalable, secure & AI-powered SaaS platforms across ERP, HRMS, CRM, LMS, and E-commerce domains.
Over 10 years of experience leading full-stack teams, cloud infrastructure, and enterprise-grade software delivery.

🌐 Portfolio: jmrashed.github.io
✉️ Email: [email protected]
💼 LinkedIn: linkedin.com/in/jmrashed
📝 Blog: medium.com/@jmrashed
💻 GitHub: github.com/jmrashed

“Need a Reliable Software Partner? I build scalable, secure & modern solutions for startups and enterprises.”