README

简介

Laravel Fortify 是一个与前端无关的 Laravel 认证后端。Fortify 为 Laravel Jetstream 的注册、认证和双因素认证功能提供动力。

• 官方文档
  • 安装
    • Fortify 服务提供者
    • Fortify 功能
    • 禁用视图
  • 认证
    • 自定义用户认证
  • 双因素认证
    • 启用双因素认证
    • 使用双因素认证进行认证
    • 禁用双因素认证
  • 注册
    • 自定义注册
  • 密码重置
    • 请求密码重置链接
    • 重置密码
    • 自定义密码重置
  • 电子邮件验证
    • 保护路由
  • 密码确认
• 贡献
• 行为准则
• 安全漏洞
• 许可证

官方文档

注意：想看看实现这些认证相关视图的示例？请查看他们的基于 Blade 的 Jetstream 实现！

您可以使用 Fortify（不使用 Jetstream）为您的 Laravel 应用程序提供无头认证后端。在这种情况下，您需要使用您选择的任何前端栈（Blade、Vue 等）构建自己的模板。

安装

要开始使用，请使用 Composer 安装 Fortify

composer require solumdesignum/fortify

接下来，发布 Fortify 的资源

php artisan vendor:publish --provider="Laravel\Fortify\FortifyServiceProvider"

此命令将发布 Fortify 的操作到您的 app/Actions 目录。如果该目录不存在，则会创建。此外，还会发布 Fortify 的配置文件和迁移文件。

接下来，您应该迁移您的数据库

php artisan migrate

Fortify 服务提供者

上面讨论的 vendor:publish 命令还会发布 app/Providers/FortifyServiceProvider 文件。您应该确保此文件已在 app 配置文件的 providers 数组中注册。

此服务提供者注册了 Fortify 发布的操作，指示 Fortify 在执行相关任务时使用它们。

Fortify 功能

fortify 配置文件包含一个 features 配置数组。此数组定义了 Fortify 默认会公开哪些后端路由/功能。如果您没有使用 Laravel Jetstream，我们建议您只启用以下功能，这与之前 Laravel 认证脚手架包中可用的功能集相同

'features' => [
    Features::registration(),
    Features::resetPasswords(),
    Features::emailVerification(),
],

如果您没有使用 Laravel Jetstream，您应自己实现用户资料更新、密码更新和双因素认证。

禁用视图

默认情况下，Fortify定义了返回视图的路线，例如登录屏幕或注册屏幕。但是，如果您正在构建一个由JavaScript驱动的单页面应用程序，您可能不需要这些路线。因此，您可以通过将配置文件config/fortify.php中的views配置值设置为false来完全禁用这些路线。

'views' => false,

注意：如果您选择禁用Fortify的视图，您仍然应该定义一个名为password.reset的路线，该路线负责显示您的应用程序的“重置密码”视图。这是必要的，因为Laravel的Illuminate\Auth\Notifications\ResetPassword通知将通过password.reset命名路由生成密码重置URL。

认证

要开始，我们需要指导Fortify如何返回我们的login视图。记住，Fortify是一个无头认证库。如果您想使用已经为您完成的Fortify前端实现，应使用Laravel Jetstream。

您可以使用Laravel\Fortify\Fortify类提供的适当方法来自定义所有认证视图的渲染逻辑。通常，您应该从您的FortifyServiceProvider的boot方法中调用此方法。

use Laravel\Fortify\Fortify;

Fortify::loginView(function () {
    return view('auth.login');
});

Fortify将负责生成返回此视图的/login路线。您的login模板应包含一个表单，该表单向/login发送POST请求。/login操作期望一个字符串电子邮件地址/用户名和一个password。电子邮件/用户名字段的名称应与fortify配置文件中的username值匹配。此外，可以提供一个布尔值remember字段，以指示用户希望使用“记住我”功能。

如果登录尝试成功，Fortify将重定向您到通过您的fortify配置文件中的home配置选项设置的URI。如果登录请求是XHR请求，将返回200 HTTP响应。

如果请求不成功，用户将被重定向回登录屏幕，并通过共享的$errors Blade模板变量提供验证错误。或者，在XHR请求的情况下，验证错误将与422 HTTP响应一起返回。

自定义用户认证

Fortify将根据提供的凭据和为您的应用程序配置的认证守卫自动检索和认证用户。然而，有时您可能希望完全自定义登录凭据的认证方式和用户的检索方式。幸运的是，Fortify允许您通过使用Fortify::authenticateUsing方法轻松地实现这一点。

此方法接受一个闭包，该闭包接收传入的HTTP请求。闭包负责验证附加到请求的登录凭据，并返回相关用户实例。如果凭据无效或找不到用户，闭包应返回null或false。通常，此方法应从您的FortifyServiceProvider的boot方法中调用。

use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Laravel\Fortify\Fortify;

Fortify::authenticateUsing(function (Request $request) {
    $user = User::where('email', $request->email)->first();

    if ($user &&
        Hash::check($request->password, $user->password)) {
        return $user;
    }
});

认证守卫

在您的 fortify.php 文件中自定义身份验证守卫时，请确保您使用的是 Fortify 正确运行所需的 StatefulGuard 实现。例如，Laravel 的 api 守卫使用无状态令牌，因此不能与 Fortify 一起使用。如果您尝试使用 Laravel Fortify 对单页面应用 (SPA) 进行身份验证，您应结合使用 Laravel 的默认 web 守卫和 Laravel Sanctum。

双因素身份验证

当启用双因素身份验证时，用户需要在身份验证过程中输入一个六位数的数字令牌。该令牌使用基于时间的单次密码（TOTP）生成，可以从任何支持 TOTP 的移动身份验证应用（如 Google Authenticator）获取。

要开始使用，您首先应确保您的应用程序的 App\Models\User 模型使用了 Laravel\Fortify\TwoFactorAuthenticatable 特性。

use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Laravel\Fortify\TwoFactorAuthenticatable;

class User extends Authenticatable
{
    use Notifiable, TwoFactorAuthenticatable;
}

接下来，您应在应用程序中构建一个屏幕，让用户可以管理他们的双因素身份验证设置。该屏幕应允许用户启用和禁用双因素身份验证，以及重新生成他们的双因素身份验证恢复码。

默认情况下，fortify 配置文件的 features 数组指示 Fortify 的双因素身份验证设置在修改之前需要 密码确认。因此，您的应用程序应在继续之前实现 Fortify 的密码确认功能。

启用双因素身份验证

要启用双因素身份验证，您的应用程序应向 /user/two-factor-authentication 发送 POST 请求。如果请求成功，用户将被重定向回之前的 URL，并将 status 会话变量设置为 two-factor-authentication-enabled。您可以在模板中检测此 status 会话变量以显示相应的成功消息。如果请求是 XHR 请求，将返回 200 HTTP 响应。

@if (session('status') == 'two-factor-authentication-enabled')
    <div class="mb-4 font-medium text-sm text-green-600">
        Two factor authentication has been enabled.
    </div>
@endif

接下来，您应向用户显示用于扫描到他们的身份验证应用中的双因素身份验证二维码。如果您使用 Blade 渲染应用程序的前端，您可以使用 twoFactorQrCodeSvg 方法检索二维码 SVG。

$request->user()->twoFactorQrCodeSvg();

如果您正在构建由 JavaScript 驱动的前端，您可以对 /user/two-factor-qr-code 发送 XHR GET 请求。此 URL 将返回包含 svg 键的 JSON 对象。

您还应显示用户的双因素恢复码。这些恢复码允许用户在没有访问他们的移动设备时进行身份验证。如果您使用 Blade 渲染应用程序的前端，您可以在认证用户上访问恢复码。

(array) $request->user()->two_factor_recovery_codes

如果您正在构建由 JavaScript 驱动的前端，您可以对 /user/two-factor-recovery-codes 发送 XHR GET 请求。此 URL 将返回包含用户恢复码的 JSON 数组。

要重新生成用户的恢复码，您的应用程序应向 /user/two-factor-recovery-codes 发送 POST 请求。

使用双因素身份验证进行身份验证

在认证过程中，Fortify 将自动将用户重定向到双因素认证挑战屏幕。但是，如果您的应用程序正在发送 XHR 登录请求，则在成功尝试认证后返回的 JSON 响应将包含一个具有 two_factor 布尔属性的 JSON 对象。您应该检查此值以确定是否需要重定向到您应用程序的双因素认证挑战屏幕。

要开始实现双因素认证功能，我们需要指导 Fortify 如何返回我们的 "挑战" 视图。请记住，Fortify 是一个无头认证库。如果您希望使用已经为您完成的 Fortify 前端实现，应使用 Laravel Jetstream。

您可以使用Laravel\Fortify\Fortify类提供的适当方法来自定义所有认证视图的渲染逻辑。通常，您应该从您的FortifyServiceProvider的boot方法中调用此方法。

use Laravel\Fortify\Fortify;

Fortify::twoFactorChallengeView(function () {
    return view('auth.two-factor-challenge');
});

Fortify 将负责生成返回此视图的 /two-factor-challenge 路由。您的 two-factor-challenge 模板应包含一个向 /two-factor-challenge 发送 POST 请求的表单。/two-factor-challenge 动作期望一个包含用户当前密码的 code 字段，或者包含用户恢复代码之一的 recovery_code 字段。

如果登录尝试成功，Fortify 将将您重定向到在您的 fortify 配置文件中配置的通过 home 配置选项指定的 URI。如果登录请求是 XHR 请求，将返回 204 HTTP 响应。

如果请求不成功，用户将被重定向回登录屏幕，并通过共享的$errors Blade模板变量提供验证错误。或者，在XHR请求的情况下，验证错误将与422 HTTP响应一起返回。

禁用双因素认证

要禁用双因素认证，您的应用程序应向 /user/two-factor-authentication 发送 DELETE 请求。请记住，Fortify 的双因素认证端点在调用之前需要 密码确认。

注册

要开始实现注册功能，我们需要指导 Fortify 如何返回我们的 register 视图。请记住，Fortify 是一个无头认证库。如果您希望使用已经为您完成的 Fortify 前端实现，应使用 Laravel Jetstream。

您可以使用Laravel\Fortify\Fortify类提供的适当方法来自定义所有认证视图的渲染逻辑。通常，您应该从您的FortifyServiceProvider的boot方法中调用此方法。

use Laravel\Fortify\Fortify;

Fortify::registerView(function () {
    return view('auth.register');
});

Fortify 将负责生成返回此视图的 /register 路由。您的 register 模板应包含一个向 /register 发送 POST 请求的表单。/register 动作期望一个字符串 name、字符串电子邮件地址/用户名、password 和 password_confirmation 字段。电子邮件/用户名字段的名称应与 fortify 配置文件中的 username 值相匹配。

如果注册尝试成功，Fortify 将将您重定向到在您的 fortify 配置文件中配置的通过 home 配置选项指定的 URI。如果登录请求是 XHR 请求，将返回 200 HTTP 响应。

如果请求未成功，用户将被重定向回注册屏幕，并且验证错误将通过共享的 $errors Blade 模板变量提供给您。或者，在 XHR 请求的情况下，验证错误将随 422 HTTP 响应返回。

自定义注册

可以通过修改 App\Actions\Fortify\CreateNewUser 动作来自定义用户验证和创建过程。

密码重置

请求密码重置链接

开始实现密码重置功能，我们需要指导Fortify如何返回我们的“忘记密码”视图。记住，Fortify是一个无头认证库。如果您希望使用已经为您完成的前端Fortify实现，请使用Laravel Jetstream。

您可以使用Laravel\Fortify\Fortify类提供的适当方法来自定义所有认证视图的渲染逻辑。通常，您应该从您的FortifyServiceProvider的boot方法中调用此方法。

use Laravel\Fortify\Fortify;

Fortify::requestPasswordResetLinkView(function () {
    return view('auth.forgot-password');
});

Fortify将负责生成返回此视图的/forgot-password路由。您的forgot-password模板应包含一个表单，该表单向/forgot-password发送POST请求。/forgot-password端点期望一个名为email的字符串字段。该字段的名称/数据库列应与fortify配置文件中的email值匹配。

如果密码重置链接请求成功，Fortify将重定向回/forgot-password路由，并向用户发送一封包含安全链接的电子邮件，用户可以使用该链接重置密码。如果请求是XHR请求，则返回200 HTTP响应。

在请求成功后重定向回/forgot-password路由后，可以使用status会话变量来显示密码重置链接请求尝试的状态。

@if (session('status'))
    <div class="mb-4 font-medium text-sm text-green-600">
        {{ session('status') }}
    </div>
@endif

如果请求不成功，用户将被重定向回请求密码重置链接的屏幕，并且可以通过共享的$errors Blade模板变量访问验证错误。或者，在XHR请求的情况下，验证错误将随422 HTTP响应返回。

重置密码

为了完成密码重置功能的实现，我们需要指导Fortify如何返回我们的“重置密码”视图。记住，Fortify是一个无头认证库。如果您希望使用已经为您完成的前端Fortify实现，请使用Laravel Jetstream。

您可以使用Laravel\Fortify\Fortify类提供的适当方法来自定义所有认证视图的渲染逻辑。通常，您应该从您的FortifyServiceProvider的boot方法中调用此方法。

use Laravel\Fortify\Fortify;

Fortify::resetPasswordView(function ($request) {
    return view('auth.reset-password', ['request' => $request]);
});

Fortify将负责生成显示此视图的路由。您的reset-password模板应包含一个表单，该表单向/reset-password发送POST请求。/reset-password端点期望一个名为email的字符串字段，一个password字段，一个password_confirmation字段，以及一个名为token的隐藏字段，该字段包含request()->route('token')的值。名为“email”的字段/数据库列应与fortify配置文件中的email值匹配。

如果密码重置请求成功，Fortify将重定向回/login路由，以便用户可以使用新密码登录。此外，还会设置一个status会话变量，以便您可以在登录屏幕上显示重置成功的状态。

@if (session('status'))
    <div class="mb-4 font-medium text-sm text-green-600">
        {{ session('status') }}
    </div>
@endif

如果请求是XHR请求，则返回200 HTTP响应。

如果请求不成功，用户将被重定向回重置密码屏幕，并且可以通过共享的$errors Blade模板变量访问验证错误。或者，在XHR请求的情况下，验证错误将随422 HTTP响应返回。

自定义密码重置

可以通过修改App\Actions\ResetUserPassword操作来自定义密码重置过程。

电子邮件验证

注册后，您可能希望用户在继续访问您的应用程序之前先验证他们的电子邮件地址。要开始，请确保在您的 fortify 配置文件的 features 数组中启用了 emailVerification 功能。接下来，您应该确保您的 App\Models\User 类实现了 MustVerifyEmail 接口。此接口已为您导入到该模型中。

完成这两个设置步骤后，新注册的用户将收到一封电子邮件，提示他们验证他们的电子邮件地址所有权。然而，我们需要通知 Fortify 如何显示电子邮件验证屏幕，该屏幕会告知用户他们需要点击电子邮件中的验证链接。

您可以使用Laravel\Fortify\Fortify类提供的适当方法来自定义所有认证视图的渲染逻辑。通常，您应该从您的FortifyServiceProvider的boot方法中调用此方法。

use Laravel\Fortify\Fortify;

Fortify::verifyEmailView(function () {
    return view('auth.verify-email');
});

当用户通过 Laravel 内置的 verified 中间件被重定向到 /email/verify 端点时，Fortify 将负责生成显示此视图的路由。

您的 verify-email 模板应包含一条信息性消息，指示用户点击发送到他们电子邮件地址的电子邮件验证链接。您可以选择向此模板添加一个按钮，该按钮触发了对 /email/verification-notification 的 POST 请求。当此端点收到请求时，将向用户发送新的验证电子邮件链接，如果之前的链接不小心删除或丢失，用户可以使用新的验证链接。

如果重新发送验证链接电子邮件的请求成功，Fortify 将带有 status 会话变量的重定向回 /email/verify 端点，允许您向用户显示一条信息性消息，告知他们操作成功。如果是 XHR 请求，将返回 202 HTTP 响应。

保护路由

要指定一个路由或一组路由要求用户之前已验证他们的电子邮件地址，您应该将 Laravel 内置的 verified 中间件附加到路由上。

Route::get('/dashboard', function () {
    // ...
})->middleware(['verified']);

密码确认

在构建您的应用程序时，您可能偶尔会有一些动作需要在执行操作之前要求用户确认他们的密码。通常，这些路由由 Laravel 内置的 password.confirm 中间件保护。要开始实现密码确认功能，我们需要指导 Fortify 如何返回我们的“密码确认”视图。记住，Fortify 是一个无头身份验证库。如果您想使用已经为您完成的 Fortify 前端实现，您应该使用 Laravel Jetstream。

您可以使用Laravel\Fortify\Fortify类提供的适当方法来自定义所有认证视图的渲染逻辑。通常，您应该从您的FortifyServiceProvider的boot方法中调用此方法。

use Laravel\Fortify\Fortify;

Fortify::confirmPasswordView(function () {
    return view('auth.confirm-password');
});

Fortify 将负责生成返回此视图的 /user/confirm-password 路由。您的 confirm-password 模板应包含一个表单，该表单向 /user/confirm-password 发送 POST 请求。/user/confirm-password 动作期望一个包含用户当前密码的 password 字段。

如果密码匹配，Fortify 将将您重定向到用户尝试访问的路由。如果是 XHR 请求，将返回 201 HTTP 响应。

如果请求不成功，用户将被重定向回密码确认屏幕，并通过共享的 $errors Blade 模板变量提供验证错误。或者在 XHR 请求的情况下，验证错误将与 422 HTTP 响应一起返回。

贡献

感谢您考虑为 Fortify 做出贡献！您可以在 这里 阅读贡献指南。

行为准则

为了确保Laravel社区对所有成员友好，请阅读并遵守行为准则。

安全漏洞

请查看我们的安全政策了解如何报告安全漏洞。

许可证

Laravel Fortify是开源软件，遵循MIT许可证。