Пакет для роботи з одноразовими паролями (OTP) у Laravel-застосунках

Радий представити наш новий пакет — spatie/laravel-one-time-passwords.

Він дозволяє безпечно створювати та надсилати одноразові паролі через email, SMS або будь-який інший зручний для вас канал. Звісно, пакет також має вбудований механізм для легкої перевірки цих паролів.

Окрім цього, ми додали Livewire-компонент, який дозволяє користувачам миттєво авторизуватися за допомогою одноразового коду.

У кращих традиціях Spatie, практично кожен елемент пакета піддається гнучкому налаштуванню.

Що таке одноразові паролі?

Одноразові паролі (OTP) — це зручний і безпечний спосіб автентифікації. Користувачам більше не потрібно запам'ятовувати складні комбінації символів.

Це унікальні коди, які діють протягом короткого часу та зазвичай надсилаються на пошту або телефон.

OTPs ідеально підходять для:

• Входу без пароля: доступ до акаунта лише через код в SMS чи пошті.
• Двофакторної автентифікації (2FA): додатковий рівень захисту до основної пари логін/пароль.

Хоча OTP за своєю природою прості (зазвичай це 4-6 цифр), наш пакет реалізує низку заходів безпеки для захисту від зловживань:

• Короткий термін дії (2 хвилини за замовчуванням).
• Перевірка походження: код можна використати лише з тієї ж IP-адреси та пристрою (User Agent), з яких він був запитаний.
• Тільки один активний OTP для користувача одночасно.
• Миттєва ануляція коду після використання.
• Захист від брутфорсу через часові обмеження (time boxing).

Усі ці функції мають розумні налаштування за замовчуванням, але ви можете змінити їх під власні потреби.

Створення та використання OTP

Після встановлення пакета перше, що потрібно зробити — додати трейт HasOneTimePasswords до вашої моделі User.

namespace App\Models;

use Spatie\OneTimePasswords\Models\Concerns\HasOneTimePasswords;

class User
{
    use HasOneTimePasswords;
    
    // ...
}

Це додасть методи для збереження та отримання паролів у таблиці one_time_passwords.

Найпростіший спосіб надіслати пароль користувачеві — викликати метод sendOneTimePassword.

$user->sendOneTimePassword();

Це створить пароль і надішле його через OneTimePasswordNotification. Вигляд сповіщення можна легко змінити.

Ось так стандартно виглядає лист на пошту:

Ви також можете створити пароль без автоматичного надсилання:

$oneTimePasswordModel = $user->createOneTimePassword();

Метод поверне екземпляр моделі OneTimePassword, що дозволить вам доставити код власним способом.

Для реалізації логіки входу використовуйте метод attemptLoginUsingOneTimePassword, який перевірить код і автоматично авторизує користувача.

Приклад реалізації:

use Spatie\OneTimePasswords\Enums\ConsumeOneTimePasswordResult;

// $result повертає статус перевірки через Enum
$result = $user->attemptLoginUsingOneTimePassword($oneTimePassword, remember: false);

if ($result->isOk()) {
     // Регенеруємо сесію після входу — це стандарт безпеки
     $request->session()->regenerate();
              
     return redirect()->intended('dashboard');
}

return back()->withErrors([
    'one_time_password' => $result->validationMessage(),
])->onlyInput('one_time_password');

Якщо вам потрібно просто перевірити код без авторизації користувача, використовуйте consumeOneTimePassword:

$result = $user->consumeOneTimePassword($oneTimePassword);

Метод поверне результат із ConsumeOneTimePasswordResult, який може мати такі значення:

• Ok: пароль вірний.
• NoOneTimePasswordsFound: у користувача немає активних кодів.
• IncorrectOneTimePassword: введено неправильний код.
• DifferentOrigin: спроба використання з іншої IP-адреси або пристрою.
• OneTimePasswordExpired: термін дії коду вичерпано.
• RateLimitExceeded: перевищено ліміт спроб.

Livewire-компонент

У пакеті вже є готовий компонент для Livewire. Щоб додати його на сторінку, просто вставте:

<livewire:one-time-password>

Він згенерує форму для введення email, а після відправки — поле для введення отриманого коду.

Після успішної перевірки пароля компонент автоматично виконає вхід у систему.

Надсилання OTP через SMS

Завдяки системі Laravel Notifications ви можете використовувати будь-який канал зв'язку. Наприклад, ось як додати підтримку SMS через Vonage.

Спершу створіть власне сповіщення, яке розширює базовий клас OneTimePasswordNotification:

namespace App\Notifications;

use Spatie\OneTimePasswords\Notifications\OneTimePasswordNotification;

class CustomOneTimePasswordNotification extends OneTimePasswordNotification
{
    public function via($notifiable): string|array
    {
        return ['vonage'];
    }

    public function toVonage(object $notifiable): VonageMessage
    {
        return (new VonageMessage)
            ->content("Ваш код для входу: {$this->oneTimePassword->password}");
    }
}

Додайте метод routeNotificationForVonage до моделі User:

namespace App\Models;
 
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
 
class User extends Authenticatable
{
    use Notifiable;
 
    public function routeNotificationForVonage($notification): string
    {
        return $this->phone_number;
    }
}

Наостанок вкажіть ваш новий клас у конфігурації config/one-time-passwords.php:

// config/one-time-passwords.php

return [
    // ...
    'notification' => App\Notifications\CustomOneTimePasswordNotification::class
];

Тепер коди надходитимуть по SMS. Все максимально просто!

На завершення

Наш новий пакет надає все необхідне для реалізації безпечної автентифікації через одноразові паролі у ваших Laravel-проєктах. Це універсальний інструмент як для простого підтвердження дій, так і для повноцінних систем входу без паролів.

Більше подробиць — у нашій докладній документації.

Якщо вам подобається цей інструмент, зверніть увагу на інші наші розробки: laravel-permission для керування правами доступу, laravel-medialibrary для роботи з медіафайлами та laravel-backup для резервного копіювання. Повний список доступний за посиланням.

Ви можете підтримати нашу роботу над open-source, придбавши наші платні продукти або підписавшись на Flare чи Mailcoach.