diadal / google2fa-laravel
A One Time Password Authentication package, compatible with Google Authenticator.
Requires
- php: >=5.4
- laravel/framework: >=5.2
- pragmarx/google2fa: ~3.0
Requires (Dev)
- orchestra/testbench-browser-kit: ~3.4|~3.5|~3.6
- phpunit/phpunit: ~5|~6|~7
Suggests
- bacon/bacon-qr-code: Required to generate inline QR Codes.
- pragmarx/recovery: Generate recovery codes.
README
Google Two-Factor Authentication Package for Laravel Useing web & admin Auth Guard
Google2FA is a PHP implementation of the Google Two-Factor Authentication Module, supporting the HMAC-Based One-time Password (HOTP) algorithm specified in RFC 4226 and the Time-based One-time Password (TOTP) algorithm specified in RFC 6238.
This package is a Laravel bridge to Google2FA's PHP package.
The intent of this package is to create QRCodes for Google2FA and check user typed codes. If you need to create backup/recovery codes, please check below.
Recovery/Backup codes
if you need to create recovery or backup codes to provide a way for your users to recover a lost account, you can use the Recovery Package.
Demos, Example & Playground
Please check the Google2FA Package Playground.
Here's an demo app showing how to use Google2FA: google2fa-example.
You can scan the QR code on this (old) demo page with a Google Authenticator app and view the code changing (almost) in real time.
Compatibility
Installing
Use Composer to install it:
composer require diadal/google2fa-laravel
If you prefer inline QRCodes instead of a Google generated url, you'll need to install BaconQrCode:
composer require bacon/bacon-qr-code
Installing on Laravel
Laravel 5.5
You don't have to do anything else, this package autoloads the Service Provider and create the Alias, using the new Auto-Discovery feature.
Laravel 5.4 and below
Add the Service Provider and Facade alias to your app/config/app.php
(Laravel 4.x) or config/app.php
(Laravel 5.x):
Diadal\Google2FALaravel\ServiceProvider::class, 'Diadal2FA' => Diadal\Google2FALaravel\Facade::class,
Publish the config file
php artisan vendor:publish --provider="Diadal\Google2FALaravel\ServiceProvider"
Using It
Use the Facade
use Diadal2FA; return Diadal2FA::generateSecretKey();
In Laravel you can use the IoC Container
$google2fa = app('diadal.google2fa'); return $google2fa->generateSecretKey();
Middleware
This package has a middleware which will help you code 2FA on your app. To use it, you just have to:
Using the middleware
Add the middleware to your Kernel.php:
protected $routeMiddleware = [ ... '2fa' => \Diadal\Google2FALaravel\Middleware::class, ];
Using it in one or more routes:
Route::get('/admin', function () { return view('admin.index'); })->middleware(['auth', '2fa']);
Configuring the view
You can set your 'ask for a one time password' view in the config file (config/google2fa.php):
/** * One Time Password View */ 'view' => 'google2fa.index',
And in the view you just have to provide a form containing the input, which is also configurable:
/** * One Time Password request input name */ 'otp_input' => 'one_time_password',
Here's a form example:
<form action="/google2fa/authenticate" method="POST"> <input name="one_time_password" type="text"> <button type="submit">Authenticate</button> </form>
One Time Password Lifetime
Usually an OTP lasts forever, until the user logs off your app, but, to improve application safety, you may want to re-ask, only for the Google OTP, from time to time. So you can set a number of minutes here:
/** * Lifetime in minutes. * In case you need your users to be asked for a new one time passwords from time to time. */ 'lifetime' => 0, // 0 = eternal
And you can decider whether your OTP will be kept alive while your users are browsing the site or not:
/** * Renew lifetime at every new request. */ 'keep_alive' => true,
Manually logging out from 2Fa
This command wil logout your user and redirect he/she to the 2FA form on the next request:
Google2FA::logout();
If you don't want to use the Facade, you may:
use Diadal\Google2FALaravel\Support\Authenticator; (new Authenticator(request()))->logout();
Events
The following events are fired:
- EmptyOneTimePasswordReceived
- LoggedOut
- LoginFailed
- LoginSucceeded
- OneTimePasswordExpired
- OneTimePasswordRequested
Documentation
Check the ReadMe file in the main Google2FA repository.
Tests
The package tests were written with phpspec.
Author
License
Google2FA is licensed under the MIT License - see the LICENSE
file for details
Contributing
Pull requests and issues are more than welcome.