README

First Factor One-Time Passwords for Laravel

This package provides secure first factor one-time passwords (OTPs) for Laravel applications. Users enter their email and receive a one-time code to sign in.

✅ Rate-limited ✅ Invalidated after use ✅ Configurable expiration ✅ Locked to the user's session ✅ Invalidated after too many failed attempts ✅ Detailed error messages ✅ Customizable mail template ✅ Auditable logs

Installation

Install the package via composer:

composer require benbjurstrom/otpz

2. Add the package's interface and trait to your Authenticatable model

// app/Models/User.php
namespace App\Models;

//...
use BenBjurstrom\Otpz\Models\Concerns\HasOtps;
use BenBjurstrom\Otpz\Models\Concerns\Otpable;

class User extends Authenticatable implements Otpable
{
    use HasFactory, Notifiable, HasOtps;
    
    // ...
}

3. Publish and run the migrations

php artisan vendor:publish --tag="otpz-migrations"
php artisan migrate

4. Add the package provided routes

// routes/web.php
Route::otpRoutes();

5. (Optional) Publish the views for custom styling

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

This package publishes the following views:

resources/
└── views/
    └── vendor/
        └── otpz/
            ├── otp.blade.php               (for entering the OTP)
            ├── components/template.blade.php
            └── mail/
                ├── notification.blade.php  (standard template)
                └── otpz.blade.php          (custom template)

6. (Optional) Publish the config file

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

This is the contents of the published config file:

<?php

return [
    /*
    |--------------------------------------------------------------------------
    | Expiration and Throttling
    |--------------------------------------------------------------------------
    |
    | These settings control the security aspects of the generated codes,
    | including their expiration time and the throttling mechanism to prevent
    | abuse.
    |
    */

    'expiration' => 5, // Minutes

    'limits' => [
        ['limit' => 1, 'minutes' => 1],
        ['limit' => 3, 'minutes' => 5],
        ['limit' => 5, 'minutes' => 30],
    ],

    /*
    |--------------------------------------------------------------------------
    | Model Configuration
    |--------------------------------------------------------------------------
    |
    | This setting determines the model used by Otpz to store and retrieve
    | one-time passwords. By default, it uses the 'App\Models\User' model.
    |
    */

    'models' => [
        'authenticatable' => env('AUTH_MODEL', App\Models\User::class),
    ],

    /*
    |--------------------------------------------------------------------------
    | Mailable Configuration
    |--------------------------------------------------------------------------
    |
    | This setting determines the Mailable class used by Otpz to send emails.
    | Change this to your own Mailable class if you want to customize the email
    | sending behavior.
    |
    */

    'mailable' => BenBjurstrom\Otpz\Mail\OtpzMail::class,

    /*
    |--------------------------------------------------------------------------
    | Template Configuration
    |--------------------------------------------------------------------------
    |
    | This setting determines the email template used by Otpz to send emails.
    | Switch to 'otpz::mail.notification' if you prefer to use the default
    | Laravel notification template.
    |
    */

    'template' => 'otpz::mail.otpz',
    // 'template' => 'otpz::mail.notification',
];

Usage

After installing Laravel Breeze or your preferred UI scaffolding, you'll need to replace the login form's login step. Instead of authenticating directly, send the OTP email and redirect the user to the OTP entry page.

Laravel Breeze Livewire Example

Replace the LoginForm authenticate method with a sendEmail method that runs the SendOtp action and returns the newly created Otp.

    use BenBjurstrom\Otpz\Actions\SendOtp;
    use BenBjurstrom\Otpz\Exceptions\OtpThrottleException;
    use BenBjurstrom\Otpz\Models\Otp;
    //...
    
    public function sendEmail(): Otp
    {
        $this->validate();

        $this->ensureIsNotRateLimited();
        RateLimiter::hit($this->throttleKey(), 300);

        try {
            (new SendOtp)->handle($this->email);
        } catch (OtpThrottleException $e) {
            throw ValidationException::withMessages([
                'form.email' => $e->getMessage(),
            ]);
        }

        RateLimiter::clear($this->throttleKey());
    }

Update the Login component's login method to call the sendEmail method and redirect to the OTP entry page.

    public function login(): void
    {
        $otp = $this->form->sendEmail();
        
        $this->redirect($otp->url);
    }

Laravel Breeze Inertia Example

Remove password from the rules array and replace the LoginRequest authenticate method with a sendEmail method that runs the SendOtp action and returns the newly created Otp.

    use BenBjurstrom\Otpz\Actions\SendOtp;
    use BenBjurstrom\Otpz\Exceptions\OtpThrottleException;
    use BenBjurstrom\Otpz\Models\Otp;
    //...
    
    public function rules(): array
    {
        return [
            'email' => ['required', 'string', 'email']
        ];
    }
    //...
    
    public function sendEmail(): Otp
    {
        $this->ensureIsNotRateLimited();
        RateLimiter::hit($this->throttleKey(), 300);

        try {
            $otp = (new SendOtp)->handle($this->email);
        } catch (OtpThrottleException $e) {
            throw ValidationException::withMessages([
                'email' => $e->getMessage(),
            ]);
        }

        RateLimiter::clear($this->throttleKey());

        return $otp;
    }

Update the AuthenticatedSessionController store method to call the sendEmail method and redirect to the OTP entry page.

    public function store(LoginRequest $request): \Symfony\Component\HttpFoundation\Response
    {
        $otp = $request->sendEmail();

        return Inertia::location($otp->url);
    }

Everything else is handled by the package components.

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

License

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

benbjurstrom / otpz

Maintainers

Details