README

此包为您的Laravel Filament应用添加了双因素认证，使用Laravel Fortify官方包。我们提供了视图和逻辑，以在您的Filament应用中启用双因素认证（2FA）。可能的认证方法包括

• 电子邮件
• 短信
• 认证应用

功能和截图

启用双因素认证（2FA）

使用认证应用作为双因素方法

使用电子邮件或短信作为双因素方法

恢复码

双因素认证挑战

安装

您可以通过composer安装此包

composer require vormkracht10/filament-2fa

如果您尚未安装 Laravel Fortify，可以通过运行以下命令进行安装

composer require laravel/fortify

php artisan fortify:install

php artisan migrate

然后您可以通过运行以下命令轻松安装插件

php artisan filament-two-factor-auth:install

然后将插件添加到您的 PanelProvider

use Vormkracht10\TwoFactorAuth\TwoFactorAuthPlugin;

// ...

->plugin(TwoFactorAuthPlugin::make())

请确保您的用户使用 TwoFactorAuthenticatable 特性

class User extends Authenticatable implements FilamentUser
{
    use HasApiTokens, HasFactory, Notifiable, TwoFactorAuthenticatable;
    // ...
}

还需要在您的用户模型上定义 two_factor_type 类型转换

use Vormkracht10\TwoFactorAuth\Enums\TwoFactorType;

// ...

protected function casts(): array
{
    return [
        'two_factor_type' => TwoFactorType::class,
    ];
}

警告

当在您的模型中使用 fillable 而不是 guarded 时，请确保将 two_factor_type 添加到 $fillable 数组中。

同时确保将包文件添加到您的 vite.config.js 文件中

// ...

export default defineConfig({
    plugins: [
        laravel({
            input: [
                // ...
            ],
            content: [
                "./vendor/vormkracht10/filament-2fa/resources/**.*.blade.php",
            ],
            refresh: true,
        }),
    ],
});

注册事件监听器

Laravel 11

如果您正在使用Laravel 11，您需要在您的 AppServiceProvider 的boot方法中注册事件监听器

use Laravel\Fortify\Events\TwoFactorAuthenticationChallenged;
use Laravel\Fortify\Events\TwoFactorAuthenticationEnabled;
use Vormkracht10\TwoFactorAuth\Listeners\SendTwoFactorCodeListener;

// ...

public function boot(): void
{
    Event::listen([
        TwoFactorAuthenticationChallenged::class,
        TwoFactorAuthenticationEnabled::class
    ], SendTwoFactorCodeListener::class);
}

Laravel < 11

如果您尚未使用Laravel 11，您可能需要手动在您的 EventServiceProvider 中注册事件监听器

use Laravel\Fortify\Events\TwoFactorAuthenticationEnabled;
use Laravel\Fortify\Events\TwoFactorAuthenticationChallenged;
use Vormkracht10\TwoFactorAuth\Listeners\SendTwoFactorCodeListener;

// ...

protected $listen = [
    TwoFactorAuthenticationChallenged::class => [
        SendTwoFactorCodeListener::class,
    ],
    TwoFactorAuthenticationEnabled::class => [
        SendTwoFactorCodeListener::class,
    ],
];

如果您想自定义视图（包括电子邮件），可以使用以下命令发布它们

php artisan vendor:publish --tag=filament-two-factor-auth-views

用法

配置

认证方法可以在 config/filament-two-factor-auth.php 文件中进行配置（该文件在安装命令期间发布）。

您可以简单地添加或删除（注释）您希望使用的功能

return [
    'options' => [
        TwoFactorType::authenticator,
        TwoFactorType::email,
        // TwoFactorType::phone,
    ],

    'sms_service' => null, // For example 'vonage', 'twilio', 'nexmo', etc.
    'send_otp_class' => null,
    'phone_number_field' => 'phone', // The field name of the phone number in your user model
];

如果您想使用短信方法，您需要提供短信服务。您可以查阅 Laravel Notifications文档 以获取现成的服务。

使用Vonage的示例

类似于 Laravel文档 中的示例，您需要在您的通知类中创建 toVonage() 方法。这就是为什么我们建议创建一个自定义通知类，该类扩展了此包中的原始 SendOTP 类

<?php

namespace App\Notifications;

use Vormkracht10\TwoFactorAuth\Notifications\SendOTP as NotificationsSendOTP;
use Illuminate\Notifications\Messages\VonageMessage;

class SendOTP extends NotificationsSendOTP
{
    /**
     * Get the Vonage / SMS representation of the notification.
     */
    public function toVonage(mixed $notifiable): VonageMessage
    {
        return (new VonageMessage)
            ->content('Your OTP is: ' . $this->getTwoFactorCode($notifiable));
    }
}

您可以通过调用通知类上的 getTwoFactorCode 方法来获取用户的双因素代码。

然后您需要在 config/filament-two-factor-auth.php 文件中设置 send_otp_class

return [
    // ...

    'sms_service' => 'vonage',
    'send_otp_class' => App\Notifications\SendOTP::class,
];

注意

请确保您的用户或通知模型具有 routeNotificationForVonage 方法，该方法返回电话号码。有关更多信息，请查看您使用的短信服务的文档。

自定义

如果您想完全自定义页面，可以在 config/filament-two-factor-auth.php 文件中覆盖类

return [
    // ...

    'login' => Login::class,
    'register' => Register::class,
    'challenge' => LoginTwoFactor::class,
    'two_factor_settings' => TwoFactor::class,
    'password_reset' => PasswordReset::class,
    'password_confirmation' => PasswordConfirmation::class,
    'request_password_reset' => RequestPasswordReset::class,
];

请确保您扩展了包中的原始类。

多租户设置

如果您在使用Filament的多租户设置中，需要在config/filament-two-factor-auth.php文件中将tenant选项设置为true。您还需要在您的面板配置中设置userMenuItems。请参考以下示例

use Vormkracht10\TwoFactorAuth\Pages\TwoFactor;

// ...

->userMenuItems([
    // ...
    'two-factor-authentication' => MenuItem::make()
        ->icon('heroicon-o-lock-closed')
        ->label(__('Two-Factor Authentication'))
        ->url(fn(): string => TwoFactor::getUrl(['tenant' => auth()->user()->organization->getRouteKey()])),
])

强制两步验证

如果您想强制用户启用两步验证，可以将以下代码添加到您的PanelProvider

->plugins([
    TwoFactorAuthPlugin::make()->forced(),
])

警告

当您使用forced方法时，请确保在使用多租户设置的情况下，在filament-two-factor-auth.php配置文件中将multi_tenancy选项设置为true。否则，强制设置将不会生效。由于用户尚未认证，我们无法在PanelProvider中检查租户。

自定义强制消息

如果您想自定义强制消息，可以发布语言文件

php artisan vendor:publish --tag="filament-two-factor-auth-translations"

然后您可以在lang/vendor/filament-two-factor-auth/en.json文件中自定义消息。您应该更改以下键

{
    "Your administrator requires you to enable two-factor authentication.": "Your custom message here.",
    "Two-Factor Authentication mandatory": "Your custom title here."
}

测试

composer test

变更日志

请参阅变更日志获取最近更改的更多信息。

贡献

请参阅贡献指南以获取详细信息。

安全漏洞

请参阅我们的安全策略了解如何报告安全漏洞。

致谢

• Baspa
• 所有贡献者

许可

MIT许可（MIT）。请参阅许可文件获取更多信息。