README

Features
Installation
- Configuration
Set Up
Usage
Compatibility
- Laravel compatibility
- Browser compatibility
  - Homestead
License

LaravelWebauthn is the adapter to use Webauthn as 2FA (two-factor authentication) or as passwordless authentication on Laravel.

Try this now on the demo application.

Features

Manage Webauthn keys registration
2nd factor authentication: add a middleware service to use a Webauthn key as 2FA
Login provider using a Webauthn key, without password

Installation

Install this package with:

composer require asbiin/laravel-webauthn

Configuration

You can publish LaravelWebauthn configuration in a file named config/webauthn.php, and resources using the vendor:publish command:

php artisan vendor:publish --provider="LaravelWebauthn\WebauthnServiceProvider"

Next, you should migrate your database:

php artisan migrate

Set Up

Option 1: add LaravelWebauthn middleware

The Webauthn middleware will force the user to authenticate their webauthn key for certain routes.

Assign the middleware to a route or a group of routes:

use LaravelWebauthn\Http\Middleware\WebauthnMiddleware;

Route::get('/home', function () {
    // ...
})->middleware(WebauthnMiddleware::class);

The Webauthn middleware will redirect the user to the webauthn login page when required.

Login via remember

When session expires, but the user have set the remember cookie, you can revalidate webauthn session by subscribing to the LaravelWebauthn\Listeners\LoginViaRemember listener:

use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        Event::subscribe(LoginViaRemember::class);
    }
}

Option 2: Passwordless authentication

You can use Webauthn to authenticate a user without a password, using only a webauthn key authentication.

To enable passwordless authentication, first add the webauthn user provider: update your config/auth.php file and change the users provider:

'providers' => [
    'users' => [
        'driver' => 'webauthn',
        'model' => App\Models\User::class,
    ],
],

Then allow your login page to initiate a webauthn login with an email identifier.

You can call webauthn.auth.options route with a POST request and an email input to get the challenge data. See Authenticate section for more details.

Disabling Views

By default LaravelWebauthn defines routes that are intended to return views for authentication and register key.

However, if you are building a JavaScript driven single-page application, you may not need these routes. For that reason, you may disable these routes entirely by setting the views configuration value within your application's config/webauthn.php configuration file to false:

'views' => false,

Cache

Note this package uses the cache to store the challenge data between the server request and the browser response. You'll need to setup a real cache driver from your config/cache.php file, and thus you can't use the array or null driver.

Usage

You will find an example of usage on asbiin/laravel-webauthn-example. You can try it right now on the demo application.

Authenticate

To authenticate with a webauthn key, the workflow is the following:

Open the webauthn.login login page. You can customize the login page view by calling Webauthn::loginViewResponseUsing. See View response

The default behavior will open the webauthn::authenticate page. You can also change the value of webauthn.views.authenticate in the configuration file.
Or: Get the publicKey challenge by calling webauthn.auth.options (if not provided).
Start the webauthn browser authentication. You can use the webauthn.js library to do this.

Send the signed data to webauthn.auth route.
The POST response will be:
- a redirect response
- or a json response with a callback data.

Example:

  <!-- load javascript part -->
  <script src="{!! secure_asset('vendor/webauthn/webauthn.js') !!}"></script>
...
  <!-- script part to run the sign part -->
  <script>
    var publicKey = {!! json_encode($publicKey) !!};

    var webauthn = new WebAuthn();

    webauthn.sign(
      publicKey,
      function (data) {
        axios.post("{{ route('webauthn.auth') }}", data)
          .then(function (response) {
            if (response.data.callback) { window.location.href = response.data.callback;}
          });
      }
    );
  </script>

If the authentication is successful, the server will use the webauthn.redirects.login configuration:

to redirect the response on a plain http call

or with a json response, like:

{
    result: true,
    callback: `webauthn.redirects.login` target url,
}

Register a new key

To register a new webauthn key, the workflow is the following:

Open the webauthn.register page. You can customize the register page view by calling Webauthn::registerViewResponseUsing. See View response

The default behavior will open the webauthn::register page. You can also change the value of webauthn.views.register in the configuration file.
Or: Get the publicKey challenge by calling webauthn.store.options (if not provided).
Start the webauthn browser registration. You can use the webauthn.js library to do this.

Send the signed data to webauthn.store route. The data should contain a name field with the webauthn key name.
The POST response will be:
- a redirect response
- or a json response with a callback data.

Example:

  <!-- load javascript part -->
  <script src="{!! secure_asset('vendor/webauthn/webauthn.js') !!}"></script>
...
  <!-- script part to run the sign part -->
  <script>
    var publicKey = {!! json_encode($publicKey) !!};

    var webauthn = new WebAuthn();

    webauthn.register(
      publicKey,
      function (data) {
        axios.post("{{ route('webauthn.store') }}", {
          ...data,
          name: "{{ $name }}",
        })
      }
    );
  </script>

If the registration is successful, the server will use the webauthn.redirects.register configuration:

to redirect the response on a plain http call

or with a json response, like:

{
    result: json serialized webauthn key value,
    callback: `webauthn.redirects.register` target url,
}

Routes

These routes are defined:

Request	Route	Description
GET `/webauthn/auth`	`webauthn.login`	The login page.
POST `/webauthn/auth/options`	`webauthn.auth.options`	Get the publicKey and challenge to initiate a WebAuthn login.
POST `/webauthn/auth`	`webauthn.auth`	Post data after a WebAuthn login validate.
GET `/webauthn/keys/create`	`webauthn.create`	The register key page.
POST `/webauthn/keys/options`	`webauthn.store.options`	Get the publicKeys and challenge to initiate a WebAuthn registration.
POST `/webauthn/keys`	`webauthn.store`	Post data after a WebAuthn register check.
DELETE `/webauthn/keys/{id}`	`webauthn.destroy`	Delete an existing key.
PUT `/webauthn/keys/{id}`	`webauthn.update`	Update key properties (name, ...).
POST `/webauthn/confirm-key`	`webauthn.key.confirm`	Post data to test a WebAuthn authentication without login.

You can customize the first part of the url by setting prefix value in the config file.

Ignore route creation

You can disable the routes creation by adding this in your AppServiceProvider:

use LaravelWebauthn\Services\Webauthn;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        Webauthn::ignoreRoutes();
    }
}

Customizing The Authentication Pipeline

The Laravel Webauthn authentication pipeline is highly inspired by the Fortify pipeline.

If you would like, you may define a custom pipeline of classes that login requests should be piped through. Each class should have an __invoke method which receives the incoming Illuminate\Http\Request instance and, like middleware, a $next variable that is invoked in order to pass the request to the next class in the pipeline.

To define your custom pipeline, you may use the Webauthn::authenticateThrough method. This method accepts a closure which should return the array of classes to pipe the login request through. Typically, this method should be called from the boot method of your App\Providers\FortifyServiceProvider class.

The example below contains the default pipeline definition that you may use as a starting point when making your own modifications:

use LaravelWebauthn\Actions\AttemptToAuthenticate;
use LaravelWebauthn\Actions\EnsureLoginIsNotThrottled;
use LaravelWebauthn\Actions\PrepareAuthenticatedSession;
use LaravelWebauthn\Services\Webauthn;
use Illuminate\Http\Request;

Webauthn::authenticateThrough(fn (Request $request) => array_filter([
    config('webauthn.limiters.login') !== null ? null : EnsureLoginIsNotThrottled::class,
    AttemptToAuthenticate::class,
    PrepareAuthenticatedSession::class,
]));

Rate Limiter

By default, Laravel Webauthn will throttle logins to five requests per minute for every email and IP address combination. You may specify a custom rate limiter with other specifications.

First define a custom rate limiter. Follow Laravel rate limiter documentation to create a new RateLimiter within the boot method of your application's App\Providers\AppServiceProvider class.

use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    protected function boot(): void
    {
        RateLimiter::for('webauthn-login', function (Request $request) {
            return Limit::perMinute(1000);
        });
    }
}

Then use this new custom rate limiter in your webauthn.limiters.login configuration:

'limiters' => [
    'login' => 'webauthn-login',
],

Events

Events are dispatched by LaravelWebauthn:

\Illuminate\Auth\Events\Failed on a failed login check.
\LaravelWebauthn\Events\WebauthnLogin on login with Webauthn check.
\LaravelWebauthn\Events\WebauthnLoginData on preparing authentication data challenge.
\LaravelWebauthn\Events\WebauthnRegister on registering a new key.
\LaravelWebauthn\Events\WebauthnRegisterData on preparing register data challenge.
\LaravelWebauthn\Events\WebauthnRegisterFailed on failing registering a new key.
\LaravelWebauthn\Events\WebauthnAuthenticate when a key has been authenticated.

View response

You can easily change the view responses with the Webauthn service.

For instance, call Webauthn::loginViewResponseUsing in your App\Providers\AppServiceProvider class:

use LaravelWebauthn\Services\Webauthn;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register(): void
    {
        Webauthn::loginViewResponseUsing(LoginViewResponse::class);
    }
}

With a LoginViewResponse class:

use LaravelWebauthn\Http\Responses\LoginViewResponse as LoginViewResponseBase;

class LoginViewResponse extends LoginViewResponseBase
{
    public function toResponse($request)
    {
        return Inertia::render('Webauthn/WebauthnLogin', [
            'publicKey' => $this->publicKey
        ])->toResponse($request);
    }
}

List of methods and their expected response contracts:

Webauthn static methods	`\LaravelWebauthn\Contracts`
`loginViewResponseUsing`	`LoginViewResponseContract`
`loginSuccessResponseUsing`	`LoginSuccessResponseContract`
`registerViewResponseUsing`	`RegisterViewResponseContract`
`registerSuccessResponseUsing`	`RegisterSuccessResponseContract`
`destroyViewResponseUsing`	`DestroyResponseContract`
`updateViewResponseUsing`	`UpdateResponseContract`

Compatibility

Laravel compatibility

This package has the following Laravel compatibility:

asbiin/laravel-webauthn	Laravel
<= 1.2.0	5.8-8.x
2.0.1	7.x-8.x
>= 3.0.0, <= 4.6.0	9.x-11.x
>= 5.0.0	>= 11.x

Browser compatibility

Most of the browsers support Webauthn.

However, your browser will refuse to negotiate a relay to your security device without the following:

a proper domain (localhost and 127.0.0.1 will be rejected by webauthn.js)
an SSL/TLS certificate trusted by your browser (self-signed is okay)
connected HTTPS on port 443 (ports other than 443 will be rejected)

Homestead

If you are a Laravel Homestead user, the default is to forward ports. You can switch from NAT/port forwarding to a private network with similar Homestead.yaml options:

sites:
  - map: homestead.test
networks:
  - type: "private_network"
    ip: "192.168.254.2"

Re-provisioning vagrant will inform your virtual machine of the new network and install self-signed SSL/TLS certificates automatically: vagrant reload --provision

If you haven't done so already, describe your site domain and network in your hosts file:

192.168.254.2 homestead.test

License

Author: Alexis Saettler

Licensed under the MIT License. View license.

asbiin / laravel-webauthn

Maintainers

Details