Download the PHP package daikazu/laravel-frontdoor without Composer

Laravel Frontdoor

A driver base Passwordless authentication for Laravel applications. Users log in by receiving a one-time code via email. No database migrations required. Session-based authentication with extensible account providers.

Features

• Passwordless Authentication - Users log in with one-time codes sent to their email
• Driver-Based Account System - Built-in testing driver to get started, then register your own driver class in config
• Optional Registration - Enable self-service account creation with compatible drivers
• Zero Database Requirements - Works out of the box with session authentication and the testing driver
• Livewire Integration - Reactive UI components with Alpine.js fallback
• Deterministic Avatars - Beautiful gradient avatars generated from email hashes
• Rate Limiting - Built-in protection against brute force attacks
• Event System - Listen to authentication and registration events throughout the flow

Requirements

• PHP 8.4+
• Laravel 12+
• Livewire 3.0+ or 4.0+

Installation

Install the package via Composer:

Publish the configuration file:

Quick Start

Get up and running in 2 minutes using the built-in testing driver.

1. Add Seed Users

Open config/frontdoor.php and add email addresses to try the package with:

2. Add the Login Component

Add the navigation component to your layout:

That's it! Users can now:

1. Click the login button
2. Enter their email address
3. Receive a one-time code via email
4. Enter the code to log in

New users (when registration is enabled) follow a slightly different flow:

1. Enter their email — prompted to create an account
2. Verify email ownership via OTP
3. Fill in the registration form
4. Account is created and user is automatically logged in

Account Drivers

Laravel Frontdoor uses a driver-based system for looking up user accounts. The active driver is set via the accounts.driver config key and determines where accounts are stored and looked up.

When a user attempts to log in:

1. The email is passed to the driver's findByEmail() method
2. The driver returns an AccountData object if the account exists, or null if not
3. If found, an OTP is generated and emailed
4. After OTP verification, the user is authenticated with a session

Testing Driver (Default)

The package ships with a testing driver for development and trying out the package. It stores seed users from your config and any new registrations in cache. It is not intended for production use.

The testing driver supports registration out of the box. To try it, enable registration in config:

New accounts registered through the UI are stored in cache and persist until the cache is cleared.

Using Your Own Driver

For production use, create a driver class that implements AccountDriver and register it in config. There are two ways to do this:

Option A: Named driver — add an entry to the drivers array and reference it by name:

Option B: FQCN — set the driver directly to the class name:

Both approaches resolve the class from Laravel's service container automatically. Named drivers are useful when you want to switch between drivers via environment variables (e.g. FRONTDOOR_ACCOUNT_DRIVER=salesforce).

Creating a Driver (Sign-in Only)

Implement the AccountDriver interface with two methods:

Then register it in config (either approach works):

That's it. No service provider registration needed.

Adding Registration Support

To support registration, implement CreatableAccountDriver instead. This extends AccountDriver with two additional methods: registrationFields() defines the form fields shown to the user, and create() handles account creation with the submitted data.

Then enable registration in config:

When a user tries to log in with an email that doesn't exist, they'll see: "No account found. Would you like to create one?" After clicking "Create account", a verification OTP is sent to confirm email ownership. Once verified, a registration form is displayed with the fields defined by registrationFields(). The submitted data is validated against each field's rules, then passed to create(). The user is automatically logged in and a welcome email is sent.

Registration Field Types

The RegistrationField value object supports these field types:

Example with all field types:

Drivers with Constructor Dependencies

If your driver needs constructor arguments that can't be auto-resolved, bind it in the container:

Then reference it in config using either approach:

The AccountData Interface

Drivers return AccountData objects. In most cases, use the built-in SimpleAccountData DTO:

If you need custom behavior (computed names, Gravatar URLs, etc.), implement the AccountData interface directly. See the interface for the full list of required methods: getId(), getName(), getEmail(), getPhone(), getAvatarUrl(), getMetadata(), getInitial(), toArray().

Registration

Registration allows users to create accounts through the login flow. When enabled, users who attempt to log in with an email that doesn't exist will see an option to create an account.

How Registration Works

1. User enters their email address
2. Driver's findByEmail() returns null (account doesn't exist)
3. UI displays: "No account found. Would you like to create one?"
4. User clicks "Create account"
5. A verification OTP is sent to the email address
6. User enters the code to verify email ownership
7. A registration form is shown with fields defined by the driver's registrationFields() method (email is locked)
8. User fills in the form and submits
9. Data is validated against each field's rules
10. Driver's create() is called with the email and form data
11. User is automatically logged in
12. A welcome email is sent (no OTP)
13. AccountRegistered event is dispatched

Requirements

For registration to work, both of these conditions must be met:

1. registration.enabled must be true in config
2. The active driver must implement CreatableAccountDriver (not just AccountDriver)

If either condition is false, the registration prompt will not appear and users cannot self-register.

Configuration

Driver Compatibility

Customizing Registration Emails

Registration uses three configurable mailables:

The verification mailable must implement OtpMailable. The welcome mailable is a plain Mailable that receives the account data via setAccount() — it does not contain an OTP code.

Reacting to Registration

Listen for the AccountRegistered event to perform post-registration actions:

To restrict who can register (e.g., only company emails), add validation rules in your driver's registrationFields() or validation logic in your create() method.

UI Components

Navigation Component

The nav-login component provides a complete authentication UI:

When not authenticated: Displays a login button that opens the OTP flow (modal or page, depending on ui.mode).

When authenticated: Displays a user dropdown with:

• User's name and email
• Avatar (gradient or custom)
• Optional account page link
• Logout button

Component Props

Modal vs Page Mode

Control the authentication experience via ui.mode:

Modal mode (default):

Page mode:

Protecting Routes

Use the frontdoor guard in middleware:

Check authentication in Blade:

Accessing User Data

The authenticated user exposes account data as properties:

Metadata keys are accessible directly as properties too. For example, if your driver returns metadata: ['role' => 'admin', 'company' => 'Acme']:

Facade API

The Frontdoor facade provides programmatic access to all authentication features:

Available Methods

requestOtp(string $email): string

Request an OTP code for an email address. Generates a code, emails it to the user, and returns the code.

Throws AccountNotFoundException if the account doesn't exist and registration is disabled.

verify(string $email, string $code): bool

Verify an OTP code and log the user in.

Returns false if the code is invalid or expired.

loginAs(string $email): bool

Log in a user directly without requiring an OTP. Useful for testing or admin impersonation.

Returns false if the account doesn't exist.

registrationFields(): RegistrationField[]

Get the registration form fields defined by the active account driver.

Throws RegistrationNotSupportedException if registration is not enabled or the driver doesn't support it.

requestEmailVerification(string $email): string

Send a verification OTP to an email address before registration. Used to confirm email ownership before showing the registration form.

If the email already exists, falls through to requestOtp() silently (prevents email enumeration). Throws RegistrationNotSupportedException if registration is not enabled.

verifyEmailOnly(string $email, string $code): bool

Verify an OTP code without logging in the user. Used during registration to confirm email ownership.

Returns false if the code is invalid or expired. Does not log in the user.

register(string $email, array $data = []): AccountData

Create a new account, auto-login the user, and send a welcome email. Validates $data against the rules defined by the driver's registrationFields(). Only works if registration is enabled and the driver supports it.

If the email already exists, falls through to requestEmailVerification() silently (prevents email enumeration).

registrationEnabled(): bool

Check if registration is enabled and supported by the current driver.

accounts(): AccountManager

Access the account manager to interact with drivers.

otp(): OtpManager

Access the OTP manager for low-level OTP operations.

Configuration Reference

Complete configuration options in config/frontdoor.php:

Events

Laravel Frontdoor dispatches events throughout the authentication and registration flow:

Listening to Events

Register listeners in EventServiceProvider:

Or use closures in AppServiceProvider:

Customization

Publishing Views

Customize the UI by publishing the views:

Views will be published to resources/views/vendor/frontdoor/.

Available views:

• components/nav-login.blade.php - Navigation login component
• livewire/login-flow.blade.php - Livewire login flow
• livewire/register-fields.blade.php - Dynamic registration form fields partial
• blade/login.blade.php - Blade fallback login page
• blade/register.blade.php - Blade email verification prompt page
• blade/register-complete.blade.php - Blade registration form page
• blade/verify.blade.php - Blade OTP verification page
• mail/otp.blade.php - OTP email template (login and verification)
• mail/welcome.blade.php - Welcome email template (post-registration, no OTP)

Custom OTP Email

Create your own mailable implementing the OtpMailable contract. The contract requires three setter methods:

Update the configuration:

Custom Avatar URL

Return a custom avatar URL from your AccountData implementation:

If getAvatarUrl() returns null, Frontdoor will generate a deterministic gradient avatar based on the email hash.

Changing Avatar Generation

Modify gradient avatar settings:

Testing

Run the test suite:

Run a specific test:

Run tests with coverage:

Run static analysis:

Format code:

Testing Your Application

Use loginAs() to bypass OTP verification in tests:

Use Mail and Cache fakes to test OTP flow:

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

• Mike Wall
• All Contributors

License

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