Download the PHP package hydrat-agency/laravel-2fa without Composer

Laravel Two-Factor Authentication

• Introduction
• Installation
• Configuration
  • Built-in
  • Custom Notification
  • Custom Policies
  • Custom Drivers
• Contribute

Introduction

This package allow you to enable two-factor authentication in your Laravel applications very easily, without the need to add middleware or any modification to your routes. It stores tokens in your database in a distinct table, so you don't need to alter your users table. Notify users about their token via mail, SMS or any custom channel.

Includes native conditionnal check to trigger or not 2FA : you may skip the check when the user is using a known browser, IP address, IP Geo location, or any custom rule.

This package was inspired by the srmklive/laravel-twofactor-authentication package, which supports the Authy 2FA auth.

Installation

1. Use composer to install the package :

2. Add the service provider to your providers array in config/app.php file like so:

3. Run the following command to publish assets :

4. Run the following command to migrate database :

5. Add the following lines in your User model (e.g App\Models\User.php)

   • Before the class declaration, add these lines:

   • Alter the class definition to implements the TwoFactorAuthenticatableContract contract :

   • Add the TwoFactorAuthenticatable trait :

6. Make sure your user model is using the Notifiable trait.

7. You need to change the login workflow by adding the authenticated method to your app\Http\Controllers\Auth\LoginController.php class.

🚀 You may also use the shorthand version if you like it most :

That's it ! Now you want to personalize your view and see the configuration section.

Building the view

When you published the package assets, a new resources/views/auth/2fa/token.blade.php file has been created. It's up to you how you design this page, but you MUST keep the token form input name and send the form to the route('auth.2fa.store') route.

You may notice a $reason variable which tells you why the 2FA auth has been triggered. It's up to you to display it to the user or not, based on your app needs.

Configuration

All configurations are set in the config/laravel-2fa.php file which have been created when you published the package.

Built-in

First of all, you will need to choose which policies applies. A Policy job is to check if the two-factor auth must occur, or if it can be skipped (e.g : the browser is known ? skeep the two-factor auth).

The policies are defined in the policy key. Rules can be combined, with an order of priority. Each policy is called, and tells the driver if it should trigger the two-factor auth. When a policy requires a two-factor auth, the check stop and its returned message will be used as the $reason in the view (see Building the view section).

If none of policies triggers, or if the policy array is empty, the two-factor authentication is skipped and the user logs in normally.

Built-in policies are :

ℹ️ Need to create your own policy ? See Custom Policies section below.

Some policies has additionnal settings, which are self-documented in the configuration file.

Cutom notification

This package uses the laravel notifications system. The built-in notification TwoFactorToken sends the two-factor token to the user via mail.

You can extend this notification and configure other channels such as SMS by extending this class :

You'll need to change the notification configuration key to specify your new notification class :

Custom policies

If you are not satisfied by built-in policies, you may overwrite an existing policy or create you own.
All policies MUST extending the AbstractPolicy.

To overwrite an existing policy, you may directly extend the policy class :

Then, change the mapping array in the settings :

ℹ️ The AbstractPolicy has 3 available properties your may use to build your Policy check in the passes() method :

Creating a policy is trivial. For example, let's say your user might activate 2FA for their account in settings. You could create a policy which verify if the user activated 2FA, and if so fails the passes() method, which result in triggering the 2FA auth :

You may also have different checks which results in different $reason messages :

After creating your policy, you may use it in configuration file :

Event better, you can create a shortname to keep your policy array clean !

Some policies need to perform actions when a user successfully log in with 2FA complete (e.g: write a cookie or something in the database). You can define your callback in the onSucceed() method of your Policy :

Custom driver

If you need more flexibility in the whole process, you can extend the BaseDriver class and change its workflow by overwriting any method.

Don't forget to update the driver key in the config file :

⚠️ If you wish to build a driver from scratch, you MUST implement the TwoFactorDriverContract.

Contribute

Feel free to contribute to the package !
If you find any security issue, please contact me at [email protected] instead of creating a public github issue.

First contribution guide

Credits

• Thomas Georgel
• All Contributors

License

The MIT License (MIT). Please see License File for more information.