Laravel 认证与授权深度解析：Sanctum、Passport、Gate 与多因子

AuthN（认证）：证明你是你（密码/Token/OAuth/MFA）
AuthZ（授权）：决定你能做什么（Gate/Policy/RBAC）
Session：服务器端有状态（默认 Breeze/Jetstream）
Token：服务器端无状态（API 首选）

# 安装
composer require laravel/breeze --dev
php artisan breeze:install
npm install && npm run build

# 提供：注册、登录、邮箱验证、密码重置
# 纯 Blade + Alpine.js，无额外依赖
# 生产环境：建议从 Breeze 开始，逐步替换为自定义

# 纯后端：提供 Auth 服务而不绑定视图
# 典型用法：前后端分离，前端 React/Vue 调用 Fortify API
# 需要手动注册路由和构建前端页面

# 团队/多团队、API Token 管理、Two-Factor Auth
# 支持 Livewire 或 Inertia.js 前端
# "大而全"的代价：模板重、自定义成本不低

小项目（< 50 用户）：Breeze
中等项目（前后端分离）：Fortify + Sanctum + 自定义前端
大型企业（多团队、2FA、API）：Jetstream（或自研基于 Fortify）

# 前后端同源（或同域名子域名）时，用 Sanctum 的 SPA 认证
# 配置：config/sanctum.php 添加 SPA 域名
# 前端携带 withCredentials + CSRF token
# 后端通过 web guard 的 session 认证用户
# 无 Token 开销，依赖同源策略 = 适合 SSR 或同域部署

API 路由：
Route::middleware(['auth:sanctum'])->get('/user', fn() => auth()->user());

# 创建 Token
$token = $user->createToken('api-token', ['read', 'write'])->plainTextToken;

# 请求携带
Authorization: Bearer {token}

# Token 能力（Abilities）
$user->tokens()->delete();                      # 撤销全部
$user->tokens()->where('name', 'web')->delete(); # 撤销指定

# 允许多平台接入（客户端 App、第三方 Web 服务）
# 标准的 OAuth 2.0 流程：授权码/客户端凭证/密码/隐式授权
# 支持 Personal Access Token（内部服务间通信）
# 比 Sanctum 重：需要管理客户端、Token、Scope
composer require laravel/passport
php artisan passport:install

1) 用户点击「用 X 登录」（302 到授权服务）
2) 用户确认授权，返回授权码（code）
3) 后端用 code + client_secret 换 access_token + refresh_token
4) 用 access_token 调用用户资源 API

# 一行接入 GitHub/Google/Facebook
composer require laravel/socialite

# 配置（config/services.php）后：
Route::get('/auth/github/redirect', [AuthController::class, 'redirect']);
Route::get('/auth/github/callback', [AuthController::class, 'callback']);

# 典型回调逻辑：取用户信息 → 查找/创建本地用户 → 登录
$user = Socialite::driver('github')->user();

// AuthServiceProvider::boot()
Gate::define('edit-post', function (User $user, Post $post) {
    return $user->id === $post->user_id;
});

// 控制器中
if (Gate::allows('edit-post', $post)) { ... }
// Blade 中
@can('edit-post', $post) ... @endcan

// php artisan make:policy PostPolicy --model=Post
class PostPolicy {
    public function update(User $user, Post $post): bool {
        return $user->id === $post->user_id;
    }
}

// 控制器 + 隐式绑定
public function update(Post $post) {
    $this->authorize('update', $post);  // 未授权抛 403
}

Route::middleware(['can:update,post'])->put('/posts/{post}', ...);
Route::middleware(['can:delete,post'])->delete('/posts/{post}', ...);

composer require spatie/laravel-permission

# 角色（Role）= 一组权限（Permission）的集合
$user->assignRole('editor');
$user->givePermissionTo('edit posts');

# 中间件
Route::middleware(['role:admin'])->get('/admin', ...);
Route::middleware(['permission:publish posts'])->post('/posts', ...);

roles: id, name, guard_name
permissions: id, name, guard_name
model_has_roles: role_id, model_type, model_id
model_has_permissions: permission_id, model_type, model_id
role_has_permissions: permission_id, role_id

# RBAC："你是 admin 就能操作"
# ABAC："你是 admin 且文章在草稿状态 且 工作时间 才能发布"
# 实现：Gate 闭包里写多条件判断，或结合 Policy
Gate::define('publish-post', function ($user, $post) {
    return $user->hasRole('editor')
        && $post->status === 'draft'
        && now()->isWeekday();
});

结构：Header.Payload.Signature
Header: 算法（HS256/RS256）
Payload: sub（用户ID）、iat（签发时间）、exp（过期时间）、自定义声明
Signature: 签名 = HMAC(Header + Payload, Secret)
# Token 自包含：服务器拿到就能验签+解码，无需 DB 查询

composer require tymon/jwt-auth

# 配置后：
$credentials = request(['email', 'password']);
if (! $token = auth('api')->attempt($credentials)) {
    return response()->json(['error' => 'Unauthorized'], 401);
}
return response()->json(compact('token'));

# Token 黑名单（Redis）
Redis::setex('blacklist:' . $jti, $ttl, 1);

# 配合 exp 和 refresh token：
# access_token 短活（15 min）、refresh_token 长活（7 天）
# refresh 时检查是否在黑名单 + 是否在「Token 家族」白名单

知识因子：密码、PIN
持有因子：手机/硬件密钥
生物因子：指纹、面部识别

# Jetstream 启用 twoFactorAuthentication
# 用户启用后需扫码绑定 Authenticator App（Google/Microsoft）
# 登录时第二步输入 6 位 TOTP 码
# 原理：基于共享密钥 + 时间窗口（30s）生成一次性码

1) 正常登录（邮箱+密码）→ 第一步通过
2) 生成临时 Token（15 min 有效）
3) 发送 SMS/邮件含一次性码，或要求 TOTP
4) 验证一次性码 → 签发正式 Session/Token
5) 设备指纹记住：下次同设备可跳过 MFA
# 设备指纹：User-Agent + IP 段 + 浏览器指纹哈希

# SMS 不安全：SIM 交换攻击、社工获取
# TOTP 比 SMS 安全（但密钥泄露=可重放）
# FIDO2/WebAuthn 最强：物理密钥，防钓鱼

# Laravel 的 Eloquent/Query Builder 自动参数绑定，避免 SQL 注入
# 但手写 DB::raw() 和 raw where 时仍可能漏
User::whereRaw("email = '$email'")     # 危险！
User::where('email', $email)           # 安全（参数绑定）

# 记录关键操作：登录/登出/密码修改/授权变更
# Laravel 事件监听：Login/Logout/PasswordReset
Event::listen(Login::class, function ($event) {
    AuditLog::create([
        'user_id' => $event->user->id,
        'action' => 'login',
        'ip' => request()->ip(),
        'user_agent' => request()->userAgent(),
    ]);
});