Authenticate users with just their device, fingerprint or biometric data. Goodbye passwords!
Authenticate users with just their device, fingerprint or biometric data. Goodbye passwords!
Authenticate users with just their device, fingerprint or biometric data. Goodbye passwords!
This enables WebAuthn authentication inside Laravel authentication driver, and comes with everything but the kitchen sink.
For Laravel 9.x supports and onwards, use Laragear WebAuthn.
Just hit the console and require it with Composer.
composer require darkghosthunter/larapassUnfortunately, using WebAuthn is not a "walk in the park", this package allows you to enable WebAuthn in the most easiest way possible.
In a nutshell, major browsers are compatible with Web Authentication API, pushing authentication to the device (fingerprints, Face ID, patterns, codes, etc) instead of plain-text passwords.
This package validates the WebAuthn payload from the devices using a custom user provider.
If you have any doubts about WebAuthn, check this small FAQ. For a more deep dive, check WebAuthn.io, WebAuthn.me and Google WebAuthn tutorial.
We need to make sure your users can register their devices and authenticate with them.
eloquent-webauthn driver.webauthn_credentials table.After that, you can quickly start WebAuthn with the included controllers and helpers to make your life easier.
eloquent-webauthn driverThis package comes with an Eloquent-compatible user provider that validates WebAuthn responses from the devices.
Go to your config/auth.php configuration file, and change the driver of the provider you're using to eloquent-webauthn.
return [
// ...
'providers' => [
'users' => [
// 'driver' => 'eloquent', // Default Eloquent User Provider
'driver' => 'eloquent-webauthn',
'model' => App\User::class,
],
]
];If you plan to create your own user provider driver for WebAuthn, remember to inject the
WebAuthnAssertValidatorto properly validate the user with the incoming response.
webauthn_credentials tableCreate the webauthn_credentials table by publishing the migration files and migrating the table:
php artisan vendor:publish --provider="DarkGhostHunter\Larapass\LarapassServiceProvider" --tag="migrations"
php artisan migrateAdd the WebAuthnAuthenticatable contract and the WebAuthnAuthentication trait to the Authenticatable user class, or any that uses authentication.
The trait is used to tie the User model to the WebAuthn data contained in the database.
### 4. Register the routes (optional)
Finally, you will need to add the routes for registering and authenticating users. If you want a quick start, just publish the controllers included in Larapass.
php artisan vendor:publish --provider="DarkGhostHunter\Larapass\LarapassServiceProvider" --tag="controllers"
You can copy-paste these route definitions in your `routes/web.php` file.
```php
use App\Http\Controllers\Auth\WebAuthnRegisterController;
use App\Http\Controllers\Auth\WebAuthnLoginController;
Route::post('webauthn/register/options', [WebAuthnRegisterController::class, 'options'])
->name('webauthn.register.options');
Route::post('webauthn/register', [WebAuthnRegisterController::class, 'register'])
->name('webauthn.register');
Route::post('webauthn/login/options', [WebAuthnLoginController::class, 'options'])
->name('webauthn.login.options');
Route::post('webauthn/login', [WebAuthnLoginController::class, 'login'])
->name('webauthn.login');
…
html
You can bypass the route list declaration if you're using the defaults. The example above includes them just for show. Be sure to create modify this script for your needs.
Also, the helper allows headers on the action request, on both registration and login.
new Larapass({
login: 'webauthn/login',
loginOptions: 'webauthn/login/options'
}).login({
email: document.getElementById('email').value,
}, {
'My-Custom-Header': 'This is sent with the signed challenge',
})You can copy-paste it and import into a transpiler like Laravel Mix, Babel or Webpack. If the script doesn't suit your needs, you're free to create your own.
You can enable it by just issuing the WebAuthn-Remember header value to true when pushing the signed login challenge from your frontend. We can do this easily with the included Javascript helper.
new Larapass.login({
email: document.getElementById('email').value
}, {
'WebAuthn-Remember': true
})Alternatively, you can add the remember key to the outgoing JSON Payload if you're using your own scripts. Both ways are accepted.
You can override this behaviour in the
AssertsWebAuthntrait.
Probably you will want to offer a way to "recover" an account if the user loses his credentials, which is basically a way to attach a new one. You can use controllers which are also published, along with these routes:
use App\Http\Controllers\Auth\WebAuthnDeviceLostController;
use App\Http\Controllers\Auth\WebAuthnRecoveryController;
Route::get('webauthn/lost', [WebAuthnDeviceLostController::class, 'showDeviceLostForm'])
->name('webauthn.lost.form');
Route::post('webauthn/lost', [WebAuthnDeviceLostController::class, 'sendRecoveryEmail'])
->name('webauthn.lost.send');
Route::get('webauthn/recover', [WebAuthnRecoveryController::class, 'showResetForm'])
->name('webauthn.recover.form');
Route::post('webauthn/recover/options', [WebAuthnRecoveryController::class, 'options'])
->name('webauthn.recover.options');
Route::post('webauthn/recover/register', [WebAuthnRecoveryController::class, 'recover'])
->name('webauthn.recover');These come with new views and translation lines, so you can override them if you're not happy with what is included.
You can also override the views in resources/vendor/larapass and the notification being sent using the sendCredentialRecoveryNotification method of the user.
After that, don't forget to add a new token broker in your config/auth.php. We will need it to store the tokens from the recovery procedure.
return [
// ...
'passwords' => [
'users' => [
'provider' => 'users',
'table' => 'password_resets',
'expire' => 60,
'throttle' => 60,
],
// New for WebAuthn
'webauthn' => [
'provider' => 'users', // The user provider using WebAuthn.
'table' => 'web_authn_recoveries', // The table to store the recoveries.
'expire' => 60,
'throttle' => 60,
],
],
];Following the same principle of the password.confirm middleware, Larapass includes a the webauthn.confirm middleware that will ask the user to confirm with his device before entering a given route.
Route::get('this/is/important', function () {
return 'This is very important!';
})->middleware('webauthn.confirm');When publishing the controllers, the WebAuthnConfirmController will be in your controller files ready to accept confirmations. You just need to register the route by just copy-pasting these:
Route::get('webauthn/confirm', 'Auth\WebAuthnConfirmController@showConfirmForm')
->name('webauthn.confirm.form');
Route::post('webauthn/confirm/options', 'Auth\WebAuthnConfirmController@options')
->name('webauthn.confirm.options');
Route::post('webauthn/confirm', 'Auth\WebAuthnConfirmController@confirm')
->name('webauthn.confirm');
…
php
public function handle(AttestationSuccessful $event)
{
$event->user->notify(
new DeviceRegisteredNotification($event->credential->getId())
);
}This package simplifies operating with the WebAuthn ceremonies (attestation and assertion). For this, use the convenient WebAuthn facade.
Use the generateAttestation and validateAttestation for your user. The latter returns the credentials validated, so you can save them manually.
json()->all(), $user
);
// And save it.
if ($credential) {
$user->addCredential($credential);
} else {
return 'Something went wrong with your device!';
}For assertion, simply create a request using generateAssertion and validate it with validateAssertion.
input('email'))->first();
// Create an assertion for the given user (or a blank one if not found);
return WebAuthn::generateAssertion($user);Then later we can verify it:
json()->all()
);
// If is valid, login the user of the credentials.
if ($credentials) {
Auth::login(
User::getFromCredentialId($credentials->getPublicKeyCredentialId())
);
}
…
php
[
'name' => env('WEBAUTHN_NAME', env('APP_NAME')),
'id' => env('WEBAUTHN_ID'),
'icon' => env('WEBAUTHN_ICON'),
],
'bytes' => 16,
'timeout' => 60,
'cache' => env('WEBAUTHN_CACHE'),
'algorithms' => [
\Cose\Algorithm\Signature\ECDSA\ES256::class,
\Cose\Algorithm\Signature\EdDSA\Ed25519::class,
\Cose\Algorithm\Signature\ECDSA\ES384::class,
\Cose\Algorithm\Signature\ECDSA\ES512::class,
\Cose\Algorithm\Signature\RSA\RS256::class,
],
'attachment' => null,
'conveyance' => 'none',
'login_verify' => 'preferred',No open issues yet, or sync has not completed.