Download the PHP package michaeldzjap/twofactor-auth without Composer

laravel-two-factor-authentication

A two-factor authentication package for Laravel >= 8 (for Laravel 5 to 7 you will need version 1 or 2 of this package)

Table of Contents

• Description
• Important
  • Optional Correction
• Installation
• Changes to the Login Process
  • Failed Verification Attempt Handling
• Using a Custom Provider
• Errors and Exceptions
• Testing

Description

This is a two-factor authentication package for Laravel. It is heavily inspired by the Laravel Two-Factor Authentication package. The main differences between this package and the aforementioned package are:

• This package currently only works out of the box with the MessageBird Verify api or the 'null' driver that goes through all the steps of the two-factor authentication process without actually doing any real verification. This could be useful for testing purposes. You can however, specify a custom provider yourself.
• This package uses throttling to limit the number of unsuccessful authentication attempts in a certain amount of time.
• The current version of this package is only guaranteed to work with Laravel >= 8. Version 2. of this package works with Laravel 5.5 to 7. Version 1. of this package works with Laravel 5.4. Versions of Laravel prior to 5.4 have not been tested.

Important

From Laravel 5.8 and onwards, the default is to use bigIncrements instead of increments for the id column on the users table. As such, the default for this package is to use the same convention for the user_id column on the two_factor_auths table. If this is not what you want, you can change this to your liking by modifying the migration files that are published for this package.

Publishing the package's migration files allows for more flexibility with regards to customising your database structure. However, it could also cause complications if you already have ran migrations as part of installing previous versions of this package. In this case you simply might want to bypass running the migrations again or only run them when in a specific environment. The Schema::hasColumn() and Schema::hasTable() methods should be of use here.

Optional Correction

Versions of this package prior to v2.3.0 incorrectly created the user_id column on the two_factor_auths table using increments instead of unsignedInteger. Practically speaking, this error is of no concern. Although there is no need to have a primary key for the user_id column, it doesn't cause any problems either. However, if for some reason you don't like this idea, it is safe to remove the primary key using a migration of the form

Note that you will need the doctrine/dbal package for this migration to work. Furthermore, if the id column on your users table is of type bigIncrements you will have to change the lines $table->unsignedInteger('user_id')->change(); to $table->unsignedBigInteger('user_id')->change(); and $table->increments('user_id')->change(); to $table->bigIncrements('user_id')->change(); respectively.

Installation

1. To install using Composer run:

   If you want to use MessageBird Verify as the two-factor authentication provider then you also need to install the MessageBird PHP api:

   and don't forget to add your MESSAGEBIRD_ACCESS_KEY and TWO_FACTOR_AUTH_DRIVER=messagebird variables to the .env. If you instead wish to use the 'null' driver (default) then do NOT define the TWO_FACTOR_AUTH_DRIVER variable in your .env.

   From Laravel 7 and onwards you will also need to install the laravel/ui package:

2. Add the service provider to the 'providers' array in config/app.php:

3. Run the following artisan command to publish the configuration, language and view files:

   If you want to publish only one of these file groups, for instance if you don't need the views or language files, you can append one of the following commands to the artisan command: --tag=config, --tag=lang or --tag-views.

4. Important: Make sure you do this step before you run any migrations for this package, as otherwise it might give you unexpected results.

   From Laravel 5.8 and on, the default is to use bigIncrements instead of increments for the id column on the users table. As such, the default for this package is to use the same convention for the user_id column on the two_factor_auths table. If this is not what you want, you can modify the published migration files for this package.

5. Run the following artisan command to run the database migrations

   This will add a mobile column to the users table and create a two_factor_auths table.

6. Add the following trait to your User model:

   Optionally, you might want to add 'mobile' to your $fillable array.

Changes to the Login Process

The following two-factor authentication routes will be added automatically:

The first route is the route the user will be redirected to once the two-factor authentication process has been initiated. The second route is used to verify the two-factor authentication token that is to be entered by the user. The showTwoFactorForm controller method does exactly what it says. There do exist cases where you might want to respond differently however. For instance, instead of loading a view you might just want to return a json response. In that case you can simply overwrite showTwoFactorForm in the TwoFactorAuthController to be discussed below.

1. Add the following import to LoginController:

   and also add the following functions:

   and

   and lastly

   You can discard the third function if you do not want to send a two-factor authentication token automatically after a successful login attempt. Instead, you might want the user to instantiate this process from the form him/herself. In that case you would have to add the required route and controller method to trigger this function yourself. The best place for this would be the TwoFactorAuthController to be discussed next.

2. Add a TwoFactorAuthController in app/Http/Controllers/Auth with the following content:

3. If you want to give textual feedback to the user when two-factor authentication fails due to an expired token or when throttling kicks in you may want to add this to resources/views/auth/login.blade.php:

Failed Verification Attempt Handling

The default behaviour is to redirect to the previous view with an error message in case token verification fails. However, there most likely are instances where you would like to handle a failed token verification attempt differently. For instance, in the case of MessageBird a token can only be verified once. Any attempt with the same token after a first failed attempt will always throw a TokenAlreadyProcessedException and hence, it would make more sense to either redirect to the /login route again to start the entire authentication process from scratch or to redirect to a view where a new token can be requested.

In order to change the default behaviour it is possible to specify either a $redirectToAfterFailure property or a protected redirectToAfterFailure method on your TwoFactorAuthController. If one of these is present (the method taking precedence over the property), the default behaviour is bypassed and the user will be redirected to the specified route. To give a simple example, suppose you simply want to redirect to the /login route after a failed verification attempt you would structure your TwoFactorAuthController like:

Redirecting a user to a route for generating a fresh authentication token would require a bit more work, but certainly is possible this way.

Using a Custom Provider

Since the v2.1.0 release it is possible to user your own custom provider. To do so your provider needs to implement MichaelDzjap\TwoFactorAuth\Contracts\TwoFactorProvider (and possibly MichaelDzjap\TwoFactorAuth\Contracts\SMSToken if you want to send the authentication token via SMS).

1. Assuming the name of your custom provider is 'dummy', you should register it with TwoFactorAuthManager from a service provider (could be \App\Providers\AppServiceProvider):

2. Add an entry for you custom provider in the 'provider' array in app/config/twofactor-auth.php:

3. Lastly, don't forget to change the name of the provider in your .env:

Errors and Exceptions

Unfortunately the MessageBird php api throws rather generic exceptions when the verification of a token fails. The only way to distinguish an expired token from an invalid token is by comparing their error messages, which obviously is not a very robust mechanism. The reason this is rather unfortunate is because in the case of an invalid token we want to give the user at least a few (3) changes to re-enter the token before throttling kicks in, whereas in the case of an expired token we just want to redirect to the login screen right away.

Testing

An example project including unit and browser tests can be found here.