README

THIS PACKAGE IS IN DEVELOPMENT, DO NOT USE (YET)

Use passkeys in your Laravel app

Passkeys let you log in without needing a password. The process can be compared to how SSH keys work.

A passkey is a unique key pair that is generated by a password manager or hardware security key. One key is public and stored on in your Laravel app, and the other is private and stored in the password manager.

When logging using a passkey, the Laravel app will generate a challenge that your password manager can solve using the stored private key. The password manager will create a secure response and sends it back to Laravel app. If the challenge is solved correctly, you're logged in.

You can learn more about how passkeys work here.

This package provides a simple way to generate passkey using a Livewire component. It also contains a Blade component that can authenticate using passkeys.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Requirements

This package contains a Livewire component to generate passkeys. Make sure you have Livewire installed in your Laravel app.

Installation

You can install the package via composer:

composer require spatie/laravel-passkeys

Next, you must set the AUTH_MODEL in your .env file to the class name of the model that should be authenticated using passkeys.

AUTH_MODEL=App\Models\User

Next, you publish the migration by the package with:

php artisan vendor:publish --tag="passkeys-migrations"

After the migration has been published you can create the passkeys table by running the migrations:

php artisan migrate

Optionally, you can publish the config file using:

php artisan vendor:publish --tag="passkeys-config"

This is the contents of the published config file:

return [
    /*
     * After a successful authentication attempt using a passkey
     * we'll redirect to this URL.
     */
    'redirect_to_after_login' => '/dashboard',

    /*
     * These class are responsible for performing core tasks regarding passkeys.
     * You can customize them by creating a class that extends the default, and
     * by specify your custom class name here
     */
    'actions' => [
        'generate_passkey_register_options' => Spatie\LaravelPasskeys\Actions\GeneratePasskeyRegisterOptionsAction::class,
        'store_passkey' => Spatie\LaravelPasskeys\Actions\StorePasskeyAction::class,
        'generate_passkey_authentication_options' => \Spatie\LaravelPasskeys\Actions\GeneratePasskeyAuthenticationOptionsAction::class,
        'find_passkey' => \Spatie\LaravelPasskeys\Actions\FindPasskeyToAuthenticateAction::class,
    ],

    /*
     * These properties will be used to generate the passkey.
     */
    'relying_party' => [
        'name' => config('app.name'),
        'id' => parse_url(config('app.url'), PHP_URL_HOST),
        'icon' => null,
    ],

    /*
     * The models used by the package. 
     * You can override this by specifying your own models
     */
    'models' => [
        'passkey' => Spatie\LaravelPasskeys\Models\Passkey::class,
        'authenticatable' => env('AUTH_MODEL', App\Models\User::class),
    ],
];

Optionally, you can publish the views using

php artisan vendor:publish --tag="passkeys-views"

Usage

There are two parts to using passkeys in your Laravel app: creating a passkey and authenticating using a passkey.

Creating a passkey

The package provides a Livewire component to generate a passkey. It is able to create a passkey for the currently logged in user. It will also show all generated passkeys.

You can include this component in your views.

<livewire:passkeys />

Here's how the component looks like:

// TODO: insert image

Authenticating using a passkey

To let your users authenticate using a passkey, you can include the authenticate-passkey Blade component in your view, typically on your login view.

<x-authenticate-passkey />

// TODO: insert image

This component will show a link that, when clicked, will start the passkey authentication process.

If the authentication is successful, the user will be redirected to the URL specified in the redirect_to_after_login key of the passkeys config file.

Customizing the look and feel of the component

To customize the look and feel of the component, you can pass HTML to the component.

<x-authenticate-passkey>
    <button class="bg-blue-500 text-white px-4 py-2 rounded">Authenticate using passkey</button>
</x-authenticate-passkey>

To customize where the user is redirected after a successful login, you can pass a URL to the redirect prop of component.

<x-authenticate-passkey redirect="/dashboard" />

Events

The package fires the Spatie\LaravelPasskeys\Events\PasskeyUsedToAuthenticateEvent when a passkey is used to authenticate. It has a property passkey that contains the Passkey model that was used to authenticate.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

This code is based on the Laracast course on passkeys by the amazing Luke Downing.

License

The MIT License (MIT). Please see License File for more information.

rabyte / laravel-passkeys

Maintainers

Details