DOCSEARCHbyAlgolia
Submit Docs

Laravel Passkeys

repository·main·Indexed 19 days ago

https://github.com/spatie/laravel-passkeys

A Laravel package for implementing passwordless authentication using passkeys. It provides Livewire and Blade components for passkey generation and authentication, allowing users to log in via OS-level password managers. The package includes customizable action classes, event listeners for registration and authentication, and guidance for integration with Inertia applications.

Tokens
6.5K
Snippets
25
Records
34
Agent score
66%

What's inside spatie/laravel-passkeys

  1. Overview of spatie/laravel-passkeys

    main

    The spatie/laravel-passkeys package provides a streamlined way to implement passkey authentication in Laravel applications. It offers two primary high-level tools:

    1. Passkey Generation: A Livewire component that simplifies the process of allowing users to create their own passkeys.
    2. Passkey Authentication: A Blade component that enables users to log in to your application using their existing passkeys, eliminating the need for traditional email/password combinations.

  2. Overview of Laravel Passkeys

    main

    spatie/laravel-passkeys is a package that enables passwordless authentication in Laravel applications using passkeys. It allows users to log in using credentials stored in OS-level password managers (like macOS Keychain, 1Password, etc.).

    The package provides:

    • A Livewire component to facilitate the generation of passkeys.
    • A Blade component to handle user authentication via passkeys.

  3. How passkeys work in Laravel

    main

    Passkeys provide a passwordless authentication mechanism using public-key cryptography.

    When a user creates a passkey, a unique key pair is generated by their password manager (e.g., 1Password, macOS Password app) or a hardware security key:

    1. Public Key: Stored within your Laravel application.
    2. Private Key: Stored securely within the user's password manager or hardware device.

    The Authentication Flow: When a user attempts to log in, your Laravel app generates a cryptographic challenge. The user's password manager solves this challenge using the stored private key and sends a secure response back to the Laravel application. If the response correctly matches the public key stored in your database, the user is authenticated without ever needing to type an email or password.

  4. Customize the authentication button using slots

    main

    You can style the trigger button for the passkey authentication process by passing your own HTML into the <x-authenticate-passkey> component's slot. This allows you to use any CSS framework (like Tailwind CSS) or custom styles for the button that initiates the authentication flow.

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

  5. Configure your User model for Passkeys

    main

    To enable passkey support, your authentication model (e.g., User) must implement the HasPasskeys interface and use the InteractsWithPasskeys trait.

    If you are using a model other than the default App\Models\User, you must set the AUTH_MODEL environment variable in your .env file to the full class name of your model.

    AUTH_MODEL=App\Models\YourCustomUser
    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;

    // ... 
}

  8. Allow passkey login in Inertia applications

    main

    To allow users to authenticate via passkey in an Inertia app, implement a login flow that interacts with the package's authentication routes.

    1. Fetch Authentication Options: Call the passkeys.authentication_options route to get the required challenge/options.
    2. Browser Authentication: Use window.startAuthentication({ optionsJSON: options }) to prompt the user.
    3. Submit Response: POST the start_authentication_response (as a JSON string) to the passkeys.login route.

    The passkeys.login route is provided by the package and will automatically redirect the user to the URL configured in config/passkeys.php upon success.

    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)
    });
}

  10. Install and initialize JavaScript dependencies

    main

    The package relies on @simplewebauthn/browser for browser-side passkey operations.

    1. Install the dependency via NPM or Yarn:
    npm install @simplewebauthn/browser
    1. Import and expose the required functions to the window object in your JavaScript entry point (e.g., resources/js/bootstrap.js) so the package components can access them:
    import {
    browserSupportsWebAuthn,
    startAuthentication,
    startRegistration,
} from '@simplewebauthn/browser'

window.browserSupportsWebAuthn = browserSupportsWebAuthn;
window.startAuthentication = startAuthentication;
window.startRegistration = startRegistration;
    1. Rebuild your assets:
    npm run build

  12. Configure redirection after passkey login

    main

    After a successful passkey authentication, the user is redirected to a specific URL. You can control this destination in two ways:

    1. Globally: Set the redirect_to_after_login key in your config/passkeys.php file.
    2. Per component: Pass a redirect prop directly to the Blade component to override the global configuration for a specific instance.
    <x-authenticate-passkey redirect="/dashboard" />