Spatie Laravel Passkeys

https://github.com/spatie/laravel-passkeys
Admin
A Laravel package that provides a simple way to integrate passkey authentication into your...
Tokens:16,628
Snippets:129
Trust Score:10
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install package via Composer

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/installation-setup.md

Requires the spatie/laravel-passkeys package using Composer.

```bash
composer require spatie/laravel-passkeys
```

--------------------------------

### Implement withPassKey function for passkey authentication

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/usage-in-inertia.md

This function fetches authentication options from the 'passkeys.authentication_options' route, starts the WebAuthn authentication, and posts the response to the 'passkeys.login' route. The 'passkeys.login' route accepts a POST request with the 'start_authentication_response' parameter as a JSON string. After successful authentication, the user is redirected to the URL set in the 'config/passkeys.php' file.

```javascript
async function withPassKey() {
    const response = await fetch(window.route("passkeys.authentication_options"));

    const options = await response.json();

    const startAuthenticationResponse = await window.startAuthentication({ optionsJSON: options });

    router.post(window.route("passkeys.login"), {
        start_authentication_response: JSON.stringify(
            startAuthenticationResponse
        )
    });
}
```

--------------------------------

### Run tests with composer test

Source: https://github.com/spatie/laravel-passkeys/blob/main/README.md

Run the package's test suite using Composer. This command is typically executed from the project root after installation.

```bash
composer test
```

--------------------------------

### Svelte component for passkey management

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/usage-in-inertia.md

Provides functions to add and delete passkeys using Inertia router and WebAuthn. The addPassKey function fetches registration options, starts registration, and posts the data. The deletePasskey function confirms and deletes. Includes markup to list passkeys and a button to add.

```svelte
<script>
    import {router} from '@inertiajs/svelte';

    async function addPassKey() {
        const response = await fetch(window.route("profile.passkeys.generate-options"));
        const options = await response.json();
        const startAuthenticationResponse = await window.startRegistration(options);
        router.post(
            window.route("profile.passkeys.store"),
            {
                options: JSON.stringify(options),
                passkey: JSON.stringify(startAuthenticationResponse)
            }
        );
    }

    function deletePasskey(id) {
        if (confirm("Are you SURE you want to delete this passkey?")) {
            router.delete(
                window.route("profile.passkeys.delete", {id})
            );
        }
    }
</script>

{#if passkeys?.length > 0}
    <h2 class="mb-4 font-bold">Your passkeys:</h2>
    <div class=" divide-y">
        {#each passkeys as passkey}
            <div class="flex justify-between items-center py-2">
                <div>
                    <p>Name: {passkey.name}</p>
                    <p>Last used at: {passkey.last_used_at || 'Never'}</p>
                </div>
                <button on:click={() => deletePasskey(passkey.id)}>Delete</button>
            </div>
        {/each}
    </div>
{/if}

<button
        class="btn"
        on:click|preventDefault={addPassKey}
>
    Add a passkey
</button>
```

--------------------------------

### Render passkey authentication component

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/authenticating-using-passkeys.md

Include this Blade component on your login view to let users authenticate with a passkey. Place it outside any form because it renders its own form element. The component displays a link that starts the passkey authentication process when clicked.

```html
<x-authenticate-passkey />
```

--------------------------------

### Customize the authenticate-passkey button via slot

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/styling-the-components.md

Passes custom HTML to the component's slot to customize the trigger. The provided button, when clicked, starts the passkey authentication process.

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

--------------------------------

### Controller method stubs for passkey creation and deletion

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/usage-in-inertia.md

Placeholder methods to be implemented in a controller, with routes protected by auth middleware. The routes are named profile.passkeys.create, profile.passkeys.delete, and profile.passkeys.generate-options.

```php
// POST profile.passkeys.create
public function storePassKey();

// DELETE profile.passkeys.delete
public function deletePasskey(string $id); 

// GET profile.passkeys.generate-options
public function generatePasskeyOptions();
```

--------------------------------

### Publish passkeys views with artisan vendor:publish --tag=passkeys-views

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/styling-the-components.md

Publishes the package's views so you can modify them as needed for further styling.

```bash
php artisan vendor:publish --tag=passkeys-views
```

--------------------------------

### Create a custom Passkey model extending the base model

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/advanced-usage/using-a-custom-passkey-model.md

Define a new model class that extends Spatie\Passkeys\Models\Passkey. Add custom properties or methods as needed.

```php
namespace App\Models;

use Spatie\Passkeys\Models\Passkey as BasePasskey;

class Passkey extends BasePasskey
{
    // Add any custom properties or methods here
}
```

--------------------------------

### Include the Livewire passkeys component

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/generating-passkeys.md

Add this component to your view to generate and display passkeys for the currently logged-in user. The default layout is basic and can be styled as needed.

```html
<livewire:passkeys />
```

--------------------------------

### Create custom StorePasskey action class

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/advanced-usage/customizing-behaviour.md

Define a custom action class that extends the default StorePasskeyAction. The handle method calls the parent to store the passkey, then adds custom logic. Use this as a template for overriding other action classes.

```php
namespace App\Actions;

use Spatie\LaravelPasskeys\Actions\StorePasskeyAction

class CustomStorePasskeyAction extends StorePasskeyAction
{
    public function handle($user, $passkey)
    {
        // Call the parent method to store the passkey
        parent::handle($user, $passkey);

        // Add your custom logic here
    }
}
```

--------------------------------

### Return user's passkeys to Inertia component

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/usage-in-inertia.md

Fetches the authenticated user's passkeys and maps them to only include id, name, and last_used_at fields, excluding data and credential_id columns to avoid JSON encoding issues.

```php
$user = auth()->user();

return Inertia::render('Profile/Settings', [
    'user' => $user,
    'passkeys' => $user->passkeys()
			->get()
			->map(fn ($key) => $key->only(['id', 'name', 'last_used_at'])),
]);
```

--------------------------------

### Post passkey data to store route

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/usage-in-inertia.md

Front-end code that posts the registration options and the passkey response to the profile.passkeys.store route. The values are JSON stringified because the server expects them as strings.

```javascript
router.post(
    window.route("profile.passkeys.store"),
    {
        options: JSON.stringify(options),
        passkey: JSON.stringify(startAuthenticationResponse)
    }
);
```

--------------------------------

### Store passkey action with validation

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/usage-in-inertia.md

Validates the request data, executes StorePasskeyAction, and redirects back on success. On failure, throws a ValidationException with a localized error message.

```php
$data = request()->validate([
    'passkey' => 'required|json',
    'options' => 'required|json',
]);

$user = auth()->user();
$storePasskeyAction = app(StorePasskeyAction::class);

try {
    $storePasskeyAction->execute(
        $user,
        $data['passkey'],
        $data['options'],
        request()->getHost(),
        ['name' => Str::random(10)],
    );

	// Redirect back
	return redirect()->back();

} catch (Throwable $e) {
    throw ValidationException::withMessages([
        'name' => __('passkeys::passkeys.error_something_went_wrong_generating_the_passkey'),
    ]);
}
```

--------------------------------

### Register custom action in config/passkeys.php

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/advanced-usage/customizing-behaviour.md

Register the custom action class in the 'actions' array of the config file. Replace the default 'store_passkey' entry with the fully qualified class name of your custom action.

```php
// config/passkeys.php

return [
    // ...
    'actions' => [
        'store_passkey' => App\Actions\CustomStorePasskeyAction::class,
    ],
];
```

--------------------------------

### Generate passkey registration options

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/usage-in-inertia.md

Controller method that uses GeneratePasskeyRegisterOptionsAction to generate a JSON string of credentials contextual to the logged-in user, which is returned to the front-end.

```php
public function generatePasskeyOptions()
{
    $generatePassKeyOptionsAction = app(GeneratePasskeyRegisterOptionsAction::class);
    
    return $generatePassKeyOptionsAction->execute(auth()->user());
}
```

--------------------------------

### Update config/passkeys.php to use the custom model

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/advanced-usage/using-a-custom-passkey-model.md

Set the 'passkey_model' configuration key to the fully qualified class name of your custom model. This tells the package to use your model instead of the default.

```php
// config/passkeys.php

return [
    // ...
    'models' => [
        // The model used to store passkeys
        'passkey_model' => App\Models\Passkey::class,
    ],
];
```

--------------------------------

### Set custom redirect URL for passkey authentication

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/authenticating-using-passkeys.md

Pass a URL to the redirect prop to override the default redirect location after successful authentication. The default is the URL specified in the redirect_to_after_login key of the passkeys config file.

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

--------------------------------

### Add passkey login button to Login component

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/usage-in-inertia.md

Add this button to your Login component to allow users to authenticate with a passkey. It triggers the withPassKey function when clicked.

```html
<button on:click={withPassKey}>Authenticate with a passkey</button>
```

--------------------------------

### Add HasPasskeys interface and InteractsWithPasskeys trait to user model

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/installation-setup.md

Update your user model to implement the HasPasskeys interface and use the InteractsWithPasskeys trait. This is required for any model used to authenticate with passkeys.

```php
namespace App\Models;

use Spatie\LaravelPasskeys\Models\Concerns\HasPasskeys;
use Spatie\LaravelPasskeys\Models\Concerns\InteractsWithPasskeys;
// ...

class User extends Authenticatable implements HasPasskeys
{
    use HasFactory, Notifiable, InteractsWithPasskeys;

    // ... 
}
```

--------------------------------

### Delete passkey by ID

Source: https://github.com/spatie/laravel-passkeys/blob/main/docs/basic-usage/usage-in-inertia.md

Deletes the passkey belonging to the authenticated user with the given ID, flashes a success message, and redirects back.

```php
public function deletePasskey(string $id)
{
    auth()->user()->passkeys()->where('id', $id)->delete();
    flash()->success('Passkey deleted successfully');

    return redirect()->back();
}
```
Tokens:
Raw