laravel-auth

涵盖 Laravel 13 的身份验证与授权生态：Sanctum （API 令牌、SPA 身份验证）、Passport（OAuth2 服务端）、Fortify（无头 自定义 UI 身份验证）、Socialite（社交登录）、入门套件、策略与 Gate、 电子邮件验证、密码重置、会话管理、CSRF / PreventRequestForgery、加密和哈希。包含 FuseCore 模块化 项目的身份验证集成模式（User 模块、通过策略进行跨模块授权）。

Laravel 身份验证与授权

Agent 工作流（强制）

在进行任何实现之前，先并行启动 3 个 Agent，每个调用一次 Agent，并提供一个 name：

1. fuse-ai-pilot:explore-codebase - 检查现有身份验证设置、守卫和策略
2. fuse-ai-pilot:research-expert - 通过 Context7 核实最新的 Laravel 13 身份验证文档
3. mcp__context7__query-docs - 查询特定模式（Sanctum、Passport 等）

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

概览

Laravel 提供完整的身份验证与授权生态。请根据需求进行选择：

软件包	最适合	复杂度
Starter Kits	新项目、快速设置	低
Sanctum	API 令牌、SPA 身份验证	低
Fortify	自定义 UI、无头后端	中
Passport	OAuth2 服务端、第三方访问	高
Socialite	社交登录（Google、GitHub）	低

---

关键规则

1. 使用策略进行模型授权 - 不要使用内联 if 检查
2. 始终对密码进行哈希处理 - 使用 Hash::make() 或 'hashed' cast
3. 登录后重新生成会话 - 防止会话固定攻击
4. 在生产环境中使用 HTTPS - 安全 Cookie 所必需
5. 定义令牌权限 - 遵循最小权限原则

---

架构

app/
├── Http/
│   ├── Controllers/
│   │   └── Auth/              ← Auth controllers (if manual)
│   └── Middleware/
│       └── Authenticate.php   ← Redirects unauthenticated
├── Models/
│   └── User.php               ← HasApiTokens trait (Sanctum)
├── Policies/                  ← Authorization policies
│   └── PostPolicy.php
├── Providers/
│   └── AppServiceProvider.php ← Gate definitions
└── Actions/
    └── Fortify/               ← Fortify actions (if used)
        ├── CreateNewUser.php
        └── ResetUserPassword.php

config/
├── auth.php                   ← Guards & providers
├── sanctum.php                ← API token config
└── fortify.php                ← Fortify features

---

FuseCore 集成

在 FuseCore 项目中工作时，身份验证遵循模块化结构：

FuseCore/
├── Core/                      # Infrastructure (priority 0)
│   └── App/Contracts/
│       └── AuthServiceInterface.php  ← Auth contract
│
├── User/                      # Auth module (existing)
│   ├── App/
│   │   ├── Models/User.php    ← HasApiTokens trait
│   │   ├── Http/
│   │   │   ├── Controllers/
│   │   │   │   ├── AuthController.php
│   │   │   │   └── TokenController.php
│   │   │   ├── Requests/
│   │   │   │   ├── LoginRequest.php
│   │   │   │   └── RegisterRequest.php
│   │   │   └── Resources/UserResource.php
│   │   ├── Policies/UserPolicy.php
│   │   └── Services/AuthService.php
│   ├── Config/
│   │   └── sanctum.php        ← Sanctum config (module-level)
│   ├── Database/Migrations/
│   ├── Routes/api.php         ← Auth routes
│   └── module.json            # dependencies: []
│
└── {YourModule}/              # Depends on User module
    ├── App/Policies/          ← Module-specific policies
    └── module.json            # dependencies: ["User"]

FuseCore 身份验证检查清单

• 将身份验证代码放在 /FuseCore/User/ 模块中
• 将策略放在模块的 /App/Policies/ 中
• 将身份验证路由放在 /FuseCore/User/Routes/api.php 中
• 将 Sanctum 配置放在 /FuseCore/User/Config/sanctum.php 中
• 在其他模块的 module.json 中声明 "User" 依赖
• 在模块路由中使用 auth:sanctum 中间件

跨模块授权

// In FuseCore/{Module}/Routes/api.php
Route::middleware(['api', 'auth:sanctum'])->group(function () {
    Route::apiResource('posts', PostController::class);
});

// In FuseCore/{Module}/App/Http/Controllers/PostController.php
public function update(UpdatePostRequest $request, Post $post)
{
    $this->authorize('update', $post);  // Uses PostPolicy
    // ...
}

→ 完整的模块模式请参阅 fusecore skill。

---

决策指南

身份验证方式

Need auth scaffolding? → Starter Kit
├── Yes → Use React/Vue/Livewire starter kit
└── No → Building custom frontend?
    ├── Yes → Use Fortify (headless)
    └── No → API only?
        ├── Yes → Sanctum (tokens)
        └── No → Session-based

令牌类型

Third-party apps need access? → Passport (OAuth2)
├── No → Mobile app?
│   ├── Yes → Sanctum API tokens
│   └── No → SPA on same domain?
│       ├── Yes → Sanctum SPA auth (cookies)
│       └── No → Sanctum API tokens

---

核心概念

概念	说明	参考
守卫	定义用户如何进行身份验证（会话、令牌）	authentication.md
提供者	定义从何处获取用户（数据库）	authentication.md
Gate	基于闭包的授权，用于简单检查	authorization.md
策略	与模型关联的基于类的授权	authorization.md
权限	令牌权限（Sanctum/Passport 作用域）	sanctum.md

---

参考指南

概念（原因与架构）

主题	参考资料	何时查阅
身份验证	authentication.md	守卫、提供程序、登录流程
授权	authorization.md	门与策略、访问控制
Sanctum	sanctum.md	API 令牌、SPA 身份验证
Passport	passport.md	OAuth2 服务端、第三方访问
Fortify	fortify.md	无头身份验证、双重身份验证
Socialite	socialite.md	社交登录提供程序
入门套件	starter-kits.md	身份验证脚手架
电子邮件验证	verification.md	MustVerifyEmail、verified 中间件
密码重置	passwords.md	忘记密码流程
会话	session.md	会话驱动程序、闪存数据
CSRF	csrf.md	表单保护、AJAX 令牌
加密	encryption.md	数据加密（非密码）
哈希	hashing.md	密码哈希

模板（完整代码）

模板	使用场景
LoginController.php.md	手动身份验证控制器
GatesAndPolicies.php.md	门和策略示例
PostPolicy.php.md	含 before 过滤器的完整策略类
sanctum-setup.md	Sanctum 配置与测试
PassportSetup.php.md	OAuth2 服务端设置
FortifySetup.php.md	Fortify 配置与双重身份验证
SocialiteController.php.md	社交登录与测试
PasswordResetController.php.md	密码重置流程

---

最佳实践

应做事项

• 新项目使用入门套件
• 为所有模型定义策略
• 设置令牌过期时间
• 对登录尝试实施速率限制
• 对敏感操作使用 verified 中间件
• 定期清理过期令牌

不应做事项

• 不要存储明文密码
• 登录时不要跳过会话重新生成
• Sanctum 足以满足需求时，不要使用 Passport
• 不要忘记清理过期令牌
• 不要在生产环境中忽略 HTTPS
• 不要将授权逻辑放在控制器中

---

Laravel 13 说明

PreventRequestForgery（原 VerifyCsrfToken）

Laravel 13 将 VerifyCsrfToken 重命名为 PreventRequestForgery。该中间件通过 Sec-Fetch-Site 标头添加来源检查，并在必要时回退到 CSRF 令牌，以阻止有状态路由上的跨源 CSRF 攻击。

// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->preventRequestForgery(except: ['stripe/*', 'webhook/*']);
    // $middleware->preventRequestForgery(originOnly: true);    // no token fallback
    // $middleware->preventRequestForgery(allowSameSite: true); // accept same-site
})

• 将每个 VerifyCsrfToken::class 引用迁移为 PreventRequestForgery::class（VerifyCsrfToken / ValidateCsrfToken 仍作为已弃用的别名）
• 排除项：preventRequestForgery(except: [...])
• 无状态 API（Sanctum 令牌）不受影响