Download the PHP package asbiin/laravel-webauthn without Composer

Webauthn adapter for Laravel

• Features
• Installation
  • Configuration
• Set Up
  • Option 1: add LaravelWebauthn middleware
  • Login via remember
  • Option 2: Passwordless authentication
  • Disabling Views
  • Cache
• Usage
  • Authenticate
  • Register a new key
  • Routes
  • Ignore route creation
  • Customizing The Authentication Pipeline
  • Rate Limiter
  • Events
  • View response
• 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:

Configuration

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

Next, you should migrate your database:

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:

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:

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:

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 authentication 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:

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:

1. 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.

2. Or: Get the publicKey challenge by calling webauthn.auth.options (if not provided).

3. Start the webauthn browser authentication. You can use the webauthn.js library to do this.

   Send the signed data to webauthn.auth route.

4. The POST response will be:
   • a redirect response
   • or a json response with a callback data.

Example:

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:

Register a new key

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

1. 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.

2. Or: Get the publicKey challenge by calling webauthn.store.options (if not provided).

3. 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.

4. The POST response will be:
   • a redirect response
   • or a json response with a callback data.

Example:

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:

Routes

These routes are defined:

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:

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:

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.

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

Events

Events are dispatched by LaravelWebauthn:

• \LaravelWebauthn\Events\WebauthnLogin on login with Webauthn check.
• \LaravelWebauthn\Events\WebauthnLoginData on preparing authentication data challenge.
• \Illuminate\Auth\Events\Failed on a failed login check.
• \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.

View response

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

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

With a LoginViewResponse class:

List of methods and their expected response contracts:

Compatibility

Laravel compatibility

This package has the following Laravel compatibility:

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:

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:

License

Author: Alexis Saettler

Copyright © 2019–2024.

Licensed under the MIT License. View license.