06.5.4.11 Sanctum 与 Passport 认证
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.5 PHP 后端 / 06.5.4 Laravel
覆盖范围
- Sanctum 个人访问令牌与 SPA Cookie 两种认证形态
- token abilities、过期时间与能力校验中间件
- Passport OAuth2 授权码、刷新令牌、作用域与吊销
- 两种方案选型、多 guard 衔接与安全要点
认证基础概念(守卫、中间件、会话)见 06.5.1.2 路由中间件与请求处理;本页聚焦 API 认证纵深。
06.5.4.11-001 Sanctum 支持哪两种认证形态,分别面向什么场景?
一句话结论
Sanctum 提供两种并列形态:一是为移动端/第三方 API 签发个人访问令牌(Bearer Token),二是为同域或跨域 SPA 提供基于 Cookie 会话的认证;前者无状态令牌,后者复用 Laravel 会话 guard。
概念解释
令牌形态在请求头携带 token,服务端按令牌查表识别用户;SPA 形态先通过 CSRF 接口获取会话 Cookie,后续请求携带 Cookie,认证走 session guard 并由 Sanctum 配置允许的前端域名跨域访问。
原理流程
- 令牌形态:登录后
createToken生成令牌字符串,客户端请求头Authorization: Bearer。 - SPA 形态:前端先调 CSRF Cookie 接口,再提交登录,会话 Cookie 保持登录态。
- 受保护路由经
auth:sanctum中间件识别两种来源。 - 识别出的用户注入请求。
代码或图示
// 令牌签发
$token = $user->createToken('mobile-app', ['orders:read', 'orders:write']);
return response()->json(['token' => $token->plainTextToken]);
// 路由保护
Route::middleware('auth:sanctum')->get('/profile', fn () => auth()->user());
常见误区
- 把两种形态混用:SPA 用令牌存前端本地存储,或移动端依赖 Cookie 会话,都会偏离方案设计。
- 以为 Sanctum 只是 Passport 的简化令牌库:它同时覆盖 SPA Cookie 会话认证,配置项与令牌体系是两套入口。
追问
- 两种形态能否在同一项目共存?答:可以,同一应用既发 API 令牌也允许 SPA 登录;守卫与中间件配置分别按入口处理,具体配置键以当前版本
config/sanctum.php为准。 - SPA 跨域 Cookie 需要什么配置?答:在 Sanctum 配置中列出允许的前端域名,并正确设置会话域、同站策略与 CORS;具体字段名核对当前版本配置文件。
06.5.4.11-002 个人访问令牌如何签发,plainTextToken 与存储值有什么区别?
一句话结论
createToken 返回结果包含 accessToken 模型与 plainTextToken;数据库只存令牌哈希(或标识+哈希,存储形式以当前版本为准),明文 plainTextToken 只在签发时返回一次,之后无法再次查看。
概念解释
与密码哈希同理:令牌明文不入库,泄露数据库不直接暴露可用令牌;验证时用提交的令牌重新计算哈希比对。令牌前缀用于快速定位记录。
原理流程
- 用户请求签发,生成随机明文令牌。
- 对明文做哈希后写入令牌表,关联用户与能力。
- 明文随响应返回客户端,之后不再出现。
- 请求携带明文,服务端哈希后查表匹配。
代码或图示
$tokenResult = $user->createToken('admin-console', ['read']);
// 只在首次响应中下发:
echo $tokenResult->plainTextToken;
// 令牌模型可读取元信息:
// $tokenResult->accessToken->abilities
常见误区
- 把
plainTextToken回存到用户表或日志:明文泄露等于令牌泄露,日志只记录令牌前缀与标识。 - 签发后想从数据库找回明文:设计上不可恢复,丢失只能吊销旧令牌重新签发。
追问
- 令牌表结构包含哪些字段?答:通常有 tokenable 关联(用户类型与 ID)、名称、能力、哈希、过期时间等;具体列名与索引以当前版本迁移文件为准(待确认)。
- 能力如何与令牌绑定?答:签发时传入 abilities 数组,随令牌记录持久化,校验时按能力匹配。
06.5.4.11-003 token abilities(能力域)如何定义与校验?
一句话结论
abilities 是签发时绑定到令牌的字符串权限集合,如 orders:read、orders:write;请求通过 ability 或 abilities 中间件校验当前令牌是否具备所需能力,校验发生在用户认证之后。
概念解释
能力域是令牌级粗粒度授权,与用户角色/RBAC 不同:同一用户的不同设备令牌可以有不同能力,例如只读令牌不能写数据。能力字符串约定 资源:动作 形式。
原理流程
- 签发时定义 abilities 列表。
- 受保护路由挂
ability:orders:write中间件。 - 中间件解析当前令牌,读取其 abilities。
- 匹配通过放行,否则返回未授权响应。
代码或图示
Route::middleware(['auth:sanctum', 'ability:orders:write'])
->post('/orders', [OrderController::class, 'store']);
// 多能力中间件(任意满足其一,参数形式以版本为准)
Route::middleware(['auth:sanctum', 'abilities:orders:read,orders:write'])->get('/orders');
常见误区
- 用 abilities 替代用户角色体系:能力描述令牌能做什么,角色描述用户身份与基础权限,两层应配合。
- 签发时传
*全能力后仍在代码里做细粒度判断:全能力令牌一旦泄露影响面最大,应按最小权限签发。
追问
- 如何在代码中读取当前令牌能力?答:
auth()->user()->currentAccessToken()取当前令牌实例,读取abilities属性;具体方法名以当前版本 Sanctum 文档为准。 - 能力校验失败返回什么状态码?答:通常 403 Forbidden;响应格式由异常处理器统一控制,未认证为 401。
06.5.4.11-004 令牌过期时间如何配置与控制?
一句话结论
令牌有效期可在全局配置设置(expiration 类配置项),也可在签发时按令牌定制;过期后令牌不再通过认证,需要重新签发。全局关闭过期时令牌长期有效,风险更高。
概念解释
过期时间写入令牌记录,认证时与当前时间比较。长期令牌适合服务间集成,用户侧短期访问令牌应配合较短有效期与吊销机制。配置项名称与单位以当前版本 config/sanctum.php 为准(待确认)。
原理流程
- 读取全局令牌过期配置。
- 签发时计算过期时间并落库。
- 认证流程校验令牌未过期、未被吊销。
- 过期令牌拒绝访问,引导客户端刷新或重新登录。
代码或图示
// 签发时可携带过期时间(签名以当前版本为准,不确定时核对文档)
$token = $user->createToken('mobile', ['orders:read'], now()->addDays(7));
// 全局配置示例:过期分钟数;设为 null 表示不过期
// 'expiration' => 60 * 24 * 7,
常见误区
- 长期不过期令牌用于用户侧访问:设备丢失或泄露后无法靠过期收敛风险,必须配合吊销能力。
- 只在客户端设置过期展示:服务端不校验等于没过期,过期判断必须在服务端完成。
追问
- 令牌快到期如何平滑续期?答:Sanctum 个人令牌本身不提供 OAuth 式刷新令牌;续期由业务重新签发,或引入 Passport 的刷新令牌流程,选型见本页后续题目。
- 过期令牌能否手动续期?答:更新令牌记录的过期字段可以延长;更稳妥的做法是重新签发并轮换旧令牌。
06.5.4.11-005 SPA Cookie 认证的完整流程是什么?
一句话结论
SPA 先请求 CSRF Cookie 接口获取会话 Cookie,再提交登录凭证建立会话;之后同站/允许域名的请求携带会话 Cookie,auth:sanctum 经 session guard 识别用户,登出使会话失效。
概念解释
该形态本质是 Laravel Web 会话登录,Sanctum 负责允许跨域前端访问与会话/Cookie 配置。CSRF 防护依赖会话 Cookie 与 CSRF Token 头配合。
原理流程
- 前端 GET CSRF 接口,服务端下发会话 Cookie 与 CSRF Token。
- 前端携带 Token 头 POST 登录,校验凭证后建立会话。
- 后续 API 请求自动携带 Cookie,中间件解析会话用户。
- 登出清除会话,Cookie 失效。
代码或图示
// 路由示例(CSRF 接口与登录路由在默认骨架中已有)
Route::get('/sanctum/csrf-cookie', function () {
return response()->noContent();
});
Route::post('/login', [AuthController::class, 'login']);
Route::middleware('auth:sanctum')->get('/user', fn () => auth()->user());
常见误区
- 前端用 Bearer 令牌调 SPA 接口:Cookie 形态下走会话头,令牌逻辑不参与。
- 未配置允许域名就跨域请求:CORS 与会话 SameSite 策略会拦截,前后端域与 Cookie 配置必须一致。
追问
- 会话存储在哪里?答:由 Laravel 会话驱动配置决定(database/redis/cookie 等),与 Sanctum 令牌表相互独立。
- 多标签页共享登录态吗?答:同浏览器同会话域内共享会话 Cookie;登出后所有标签页会话失效。
06.5.4.11-006 auth:sanctum 中间件如何识别令牌与会话两种来源?
一句话结论
中间件依次检查请求是否携带 Bearer 令牌:有令牌走令牌 guard 查表识别;无令牌则回退到 session guard 读取会话用户;两种来源解析出的用户绑定到请求。
概念解释
中间件是多 guard 聚合入口:先按 API 令牌解析,再按 Web 会话解析。识别顺序与回退行为以当前版本 Sanctum 中间件源码为准(待确认),配置不当会出现会话用户被令牌覆盖等问题。
原理流程
- 请求进入
auth:sanctum中间件。 - 读取 Authorization 头中的 Bearer 令牌,存在则哈希查表。
- 令牌未命中则尝试会话 guard 恢复登录用户。
- 任一来源成功则绑定用户,都失败返回 401。
代码或图示
// 路由同时接受令牌与 Cookie 会话
Route::middleware('auth:sanctum')->group(function () {
Route::get('/profile', [ProfileController::class, 'show']);
});
常见误区
- 以为令牌优先会影响会话安全:顺序设计上令牌来自请求头,会话来自 Cookie;跨域场景应明确入口类型,避免凭证混带。
- 未登录也走到业务代码:中间件未生效时
auth()->user()为空,必须确认路由挂在中间件组内。
追问
- 能否只允许一种来源?答:可以在路由上分别使用对应 guard 中间件;
auth:sanctum是聚合入口,细分时参考 Laravel guard 配置。 - 匿名请求如何放行?答:可选中间件(
optional类)不强制认证,用户可能为空,代码内需判空;具体中间件名以版本为准。
06.5.4.11-007 Passport 在什么场景下使用,与 OAuth2 是什么关系?
一句话结论
Passport 是 Laravel 的 OAuth2 服务器实现,适用于需要第三方应用授权访问、标准授权码流程、客户端凭证与刷新令牌的开放平台场景;简单自有 API 用 Sanctum 令牌即可。
概念解释
OAuth2 解决“第三方代表用户或以自身身份访问接口”的授权问题:资源所有者授权后,客户端拿到访问令牌受限于作用域访问资源。Passport 基于 League OAuth2 服务器库(底层依赖以当前版本为准)。
原理流程
- 第三方客户端在服务器注册,获得 client_id 与 client_secret。
- 用户在授权页登录并同意授权。
- 客户端凭授权码换取访问令牌与刷新令牌。
- 后续请求携带访问令牌,服务器按作用域放行。
代码或图示
# Passport 安装与密钥生成(命令名以当前版本为准)
php artisan passport:install
php artisan passport:keys
常见误区
- 把 Passport 用于内部前后端分离:OAuth2 流程复杂,Sanctum 会话或个人令牌足够,引入 Passport 增加密钥与令牌管理成本。
- 以为 Passport 只能发授权码令牌:还支持客户端凭证等模式,具体启用范围以 Passport 配置与文档为准。
追问
- Passport 与 Sanctum 能否共存?答:可以分别服务不同入口,但 guard、令牌表与中间件要分清;长期维护两套认证会增加测试与排查成本。
- OAuth2 有哪些授权模式?答:授权码、简化模式、密码模式、客户端凭证;各模式适用客户端类型不同,当前 OAuth2 草案与 Passport 支持情况需核对文档。
06.5.4.11-008 授权码模式的完整交互步骤是什么?
一句话结论
客户端重定向到授权端点 → 用户登录并同意 → 授权端点回调客户端并附带授权码 → 客户端用 code、client_secret 换取访问令牌(与刷新令牌)→ 携带访问令牌访问资源接口。
概念解释
授权码模式保证令牌不经过浏览器 URL 长期暴露:code 短时有效且只能兑换一次。回调地址必须预先注册,防止 code 被劫持到未授权域名。
原理流程
- 客户端构造授权 URL,携带 client_id、回调地址、作用域、state。
- 用户登录并授权,服务器生成授权码并重定向回客户端。
- 客户端后端用 code 与密钥向令牌端点换取令牌。
- 访问令牌访问受保护资源,刷新令牌用于换新访问令牌。
代码或图示
// 授权 URL 参数示例(具体端点路径以 Passport 路由为准)
$query = http_build_query([
'client_id' => $clientId,
'redirect_uri' => $redirectUri,
'response_type' => 'code',
'scope' => 'orders:read',
'state' => $state,
]);
// GET /oauth/authorize?{query}
常见误区
- 在前端浏览器直接持有 client_secret:机密客户端密钥只能存后端,前端 SPA 应走 PKCE 或公共客户端流程(支持情况以版本为准)。
- 不校验 state:缺少 state 防护存在 CSRF 授权劫持风险。
追问
- 授权码有效期多长?答:通常很短且一次性使用,具体过期秒数以 Passport/OAuth2 库配置为准(待确认)。
- 回调地址不匹配会怎样?答:授权端点拒绝重定向,防止 code 泄露到注册外域名;生产应严格校验 redirect_uri 匹配规则。
06.5.4.11-009 客户端凭证模式与授权码模式有何区别?
一句话结论
客户端凭证模式下没有资源所有者(终端用户)参与,客户端用自身身份直接换取令牌,代表应用自身访问接口;授权码模式令牌代表被授权的用户,携带用户身份与用户授权范围。
概念解释
客户端凭证适合服务对服务调用:定时任务、内部系统对接。令牌归属客户端,不绑定 User 模型;授权码令牌归属用户,资源接口可读取 auth()->user()。
原理流程
- 客户端保存 client_id/client_secret。
- 直接向令牌端点提交凭证换令牌,无需用户跳转。
- 令牌按客户端配置的作用域访问资源。
- 服务端识别调用方为客户端而非终端用户。
代码或图示
// 客户端凭证令牌守卫(中间件名以 Passport 版本为准)
Route::middleware('auth:api')->get('/internal/report', function () {
// 此处无终端用户,调用方为客户端
});
常见误区
- 用客户端凭证令牌访问需要用户身份的接口:令牌无用户上下文,业务取用户会为空。
- 把服务对服务调用也走用户授权码:流程冗余,增加用户参与环节。
追问
- 客户端凭证令牌有刷新令牌吗?答:客户端凭证通常不颁发刷新令牌,凭证有效期内按需重新换取;具体行为以 Passport 令牌端点实现为准。
- 如何区分两种令牌的中间件?答:按 guard 与令牌类型配置中间件;代码内判断调用主体是客户端还是用户需结合令牌实例字段,字段名核对文档。
06.5.4.11-010 作用域(scope)如何定义与校验?
一句话结论
OAuth2 作用域在客户端注册与授权时声明,令牌携带已授权 scope 集合;资源接口通过 scope 中间件校验令牌是否覆盖所需作用域,粒度与 Sanctum abilities 类似但服务于 OAuth 令牌。
概念解释
scope 是授权边界:用户授权时看到“该应用可读取订单”,令牌只包含对应 scope。超范围请求被拒绝。scope 字符串命名约定与能力域保持一致。
原理流程
- 定义可用 scope 清单与描述。
- 客户端注册时申请 scope,授权页展示给用户确认。
- 令牌记录授权 scope。
- 接口中间件校验当前令牌 scope 包含所需值。
代码或图示
// scope 中间件示例(参数形式以 Passport 版本为准)
Route::middleware('auth:api')->middleware('scope:orders:read')
->get('/orders', [OrderController::class, 'index']);
常见误区
- scope 与用户角色混为一谈:scope 描述令牌授权边界,角色描述用户在系统内的身份,两者叠加判断。
- 授权时默认申请全部 scope:应按最小必要申请,用户同意页也应清楚列出范围。
追问
- 如何读取当前令牌的 scope?答:通过认证后的令牌实例读取 scope 属性;具体访问器方法以当前版本 Passport 文档为准。
- scope 能否在令牌生命周期内追加?答:已颁发令牌不自动扩 scope;需要新范围应重新授权或重新签发。
06.5.4.11-011 刷新令牌机制如何工作?
一句话结论
访问令牌有效期短,泄露窗口小;刷新令牌有效期长,用于在不重新走用户授权的情况下换取新的访问令牌。刷新令牌可轮换,使用后旧刷新令牌失效(具体轮换策略以版本实现为准)。
概念解释
刷新令牌存储在令牌表关联授权记录,过期或撤销后无法换新。客户端凭证模式一般不使用刷新令牌;授权码模式下刷新令牌是长期保持登录的凭证,需要安全存储。
原理流程
- 授权码兑换时同时拿到访问令牌与刷新令牌。
- 访问令牌过期,客户端提交刷新令牌到令牌端点。
- 服务器校验刷新令牌有效且未撤销,签发新访问令牌。
- 按策略轮换刷新令牌,旧令牌作废。
代码或图示
# 刷新请求示例(端点与字段以 Passport 路由为准)
POST /oauth/token
grant_type=refresh_token
refresh_token=...
client_id=...
client_secret=...
常见误区
- 刷新令牌当长期访问令牌用:它只用于换新,不应每次业务请求都携带。
- 刷新令牌存放在浏览器易被读取的位置:公共客户端存储需结合安全策略,机密令牌存后端。
追问
- 刷新令牌能否单独吊销?答:可以通过撤销授权或令牌记录使其失效;吊销方式见本页吊销题目。
- 刷新令牌过期后怎么办?答:用户需要重新走授权码流程;业务侧应处理重新登录跳转。
06.5.4.11-012 令牌如何吊销与撤销?
一句话结论
Sanctum 个人令牌可按用户删除或撤销对应令牌记录;Passport 可撤销访问令牌、刷新令牌或整个授权记录,使关联令牌集合失效。吊销后即使令牌字符串未过期也不能通过认证。
概念解释
吊销分单令牌撤销与授权整体撤销:用户退出某设备、修改密码、怀疑泄露时应吊销对应令牌。令牌表中状态字段或删除记录决定是否仍可匹配,实现方式以当前版本为准。
原理流程
- 定位用户令牌记录或 Passport 授权记录。
- 删除/标记撤销状态。
- 关联刷新令牌与访问令牌一并失效。
- 认证查表时匹配不到有效令牌,拒绝访问。
代码或图示
// Sanctum:撤销当前用户的指定令牌
$user->tokens()->where('id', $tokenId)->delete();
// 撤销当前访问令牌(示例方法以版本为准)
// auth()->user()->token()->revoke();
常见误区
- 只删客户端本地存储:服务端记录仍有效,泄露令牌继续可用,必须服务端吊销。
- 吊销后不通知旧客户端:旧令牌请求被拒后客户端应走重新登录流程。
追问
- 修改密码后是否吊销全部令牌?答:常见安全策略是改密后吊销该用户所有访问令牌,迫使重新登录;具体策略按业务安全要求定。
- Passport 撤销授权后刷新令牌还有效吗?答:撤销授权记录会使关联令牌集合失效;具体级联行为核对 Passport 令牌表与撤销实现。
06.5.4.11-013 令牌黑名单与撤销存储依赖什么?
一句话结论
吊销状态存储在服务端令牌/授权表中(数据库或对应持久化存储),认证每次查表判断;不依赖客户端自行删除。短期访问令牌可配合短过期窗口减少长期黑名单压力。
概念解释
无状态 JWT 常需额外黑名单存储吊销状态;Laravel 令牌默认服务端可查,吊销直接更新记录。存储位置与索引设计影响认证查询性能,具体表结构以迁移文件为准。
原理流程
- 令牌签发时写入持久化记录。
- 吊销时删除或标记记录。
- 认证流程查表判断有效性与过期。
- 失效记录不参与匹配,请求拒绝。
代码或图示
// 批量吊销某用户全部设备令牌
$user->tokens()->delete();
// 按能力筛选吊销只读令牌(示例)
$user->tokens()->where('name', 'legacy-app')->delete();
常见误区
- 以为令牌是纯无状态、服务端无法吊销:Laravel 令牌记录在服务端,吊销能力依赖服务端存储。
- 高频查表无索引:按令牌前缀与用户关联查询应确保表索引合理,慢查询影响认证接口。
追问
- 令牌表膨胀如何治理?答:定期清理过期与已吊销记录;清理命令或定时任务按业务保留期配置。
- 分布式部署下表数据共享吗?答:令牌表必须在共享数据库/存储中,多实例各自本地表会出现吊销不生效。
06.5.4.11-014 Sanctum 与 Passport 如何选型?
一句话结论
自有前端、移动端、第三方直连 API 用 Sanctum 令牌或会话;需要标准 OAuth2、开放平台授权委托、第三方应用走用户授权与刷新令牌流程时用 Passport;能不引入 Passport 就不引入。
概念解释
选型维度:是否有第三方代表用户访问、是否需要标准 OAuth 协议、客户端类型(机密/公共)、刷新与作用域复杂度、密钥运维成本。内部系统直连属于“资源拥有者直连”,OAuth2 多余。
原理流程
- 判断调用方:自有客户端还是外部第三方。
- 判断是否需要委托授权与标准协议兼容。
- 简单令牌/会话选 Sanctum;OAuth2 服务器选 Passport。
- 评估密钥管理、令牌表、测试与运维成本后落地。
代码或图示
自有 APP / 管理后台 -> Sanctum 个人令牌或 SPA 会话
内部服务对服务 -> Sanctum 令牌或客户端凭证(按协议要求)
开放平台第三方授权 -> Passport OAuth2 授权码 + 刷新令牌
常见误区
- 为“显得标准”给内部接口上 Passport:授权页、密钥、令牌端点全套成本无人使用。
- 反过来用 Sanctum 硬接第三方 OAuth 客户端:协议端点与令牌流程不兼容。
追问
- 未来可能开放第三方,先上 Passport 预留吗?答:早期以 Sanctum 起步,开放需求明确后再迁移;提前抽象 guard 与用户认证接口可降低迁移成本。
- 两者性能差异?答:Passport 多一层 OAuth 端点与密钥校验;Sanctum 令牌查表更轻量,实际开销以压测为准,不凭印象断言具体数值。
06.5.4.11-015 认证 guard 与用户模型如何衔接?
一句话结论
guard 定义认证查找方式(session、token、api 等),用户模型提供 Authenticatable 实现;Sanctum/Passport 注册各自 guard 或接入默认 user provider,路由中间件指定 guard 后解析出用户实例。
概念解释
guard 与 provider 分层:guard 负责请求如何识别身份,provider 负责如何按标识查用户模型。多 guard 可并存,不同入口使用不同 guard。用户模型需实现认证接口所需方法。
原理流程
- 配置 providers 指向用户模型表。
- guard 配置指定 driver 与 provider。
- 中间件按 guard 解析请求,得到用户实例。
auth()->user()返回当前认证用户。
代码或图示
// 用户模型实现认证接口(默认骨架已满足)
use Illuminate\Foundation\Auth\User as Authenticatable;
class User extends Authenticatable
{
// Sanctum 令牌关系由 HasApiTokens 特征提供(按方案选择)
}
常见误区
- 自定义用户表不接 provider:guard 找不到用户,登录与令牌解析失败。
- 一个路由混用多个 guard 却不明确顺序:用户来源判断混乱,应在中间件链上显式指定。
追问
- 多用户类型(管理员/会员)如何处理?答:可用同一表角色区分,或独立 provider/guard;模型与 provider 配置对应,具体方案按业务复杂度定。
auth()->guard('api')与默认 guard 区别?答:显式指定 guard 覆盖默认配置;不指定时取应用默认 guard。
06.5.4.11-016 令牌能力与 RBAC 角色权限如何分层?
一句话结论
令牌能力(abilities/scope)解决“这个凭证能访问哪些接口”,RBAC 角色权限解决“这个用户在系统内拥有什么身份与数据范围”;先认证用户、再校验令牌能力、最后做角色与数据权限判断。
概念解释
同一用户可能有多设备、多客户端令牌,能力可收窄;角色绑定用户,跨设备一致。数据级权限(只能看自己门店)不适合塞进令牌能力,应在业务服务内校验。
原理流程
- 中间件认证身份,绑定用户与令牌。
- ability/scope 中间件校验凭证边界。
- 业务层校验用户角色/权限。
- 数据层按归属与可见范围过滤记录。
代码或图示
// 第一层:令牌能力;第二层:用户角色;第三层:数据归属
Route::middleware(['auth:sanctum', 'ability:orders:read'])->get(
'/orders',
[OrderController::class, 'index']
);
public function index(OrderRepository $orders): Collection
{
// 角色与门店归属在服务/仓库内继续校验
return $orders->visibleTo(auth()->user());
}
常见误区
- 把角色权限压缩成令牌能力字符串:令牌收窄后角色体系被绕过,权限模型混乱。
- 只校验接口能力不校验数据归属:合法令牌可调接口,但越权读到他人数据。
追问
- 能力清单在哪里维护?答:接口中间件与签发处对照;建议在代码中集中定义能力常量,避免字符串散落。
- 角色变更后令牌能力要更新吗?答:令牌能力是签发时快照,角色变化通过重新签发令牌或业务层实时校验生效,具体策略按安全要求定。
06.5.4.11-017 API 限流如何与认证令牌结合?
一句话结论
限流按用户、令牌或客户端标识计数,防止凭证被滥用或接口被刷;Laravel 限流中间件可基于认证用户 ID、令牌 ID 或客户端 ID 做键,未认证请求按 IP 兜底。
概念解释
认证提供“谁在调用”,限流提供“调用多频繁”。多租户与开放平台场景应按客户端/令牌维度限流,避免单个令牌拖垮整体;限流键不能泄露敏感明文。
原理流程
- 请求通过认证解析出用户/令牌/客户端标识。
- 限流中间件按标识构造计数键。
- 计数器递增并判断窗口额度。
- 超限返回 429,附带重试提示头。
代码或图示
// 限流定义示例:已认证按用户 ID,未认证按 IP
RateLimiter::for('api', function (Request $request) {
return Limit::perMinute(60)->by(
$request->user()?->id ?: $request->ip()
);
});
Route::middleware(['auth:sanctum', 'throttle:api'])->group(function () {
// 受保护接口
});
常见误区
- 未认证时也按用户 ID 取键:用户为空导致键冲突或报错,应回退 IP。
- 限流键用令牌明文:日志与计数存储应使用标识或哈希,不存明文。
追问
- 服务对服务调用是否单独限流?答:建议按客户端维度设置独立额度,避免被业务用户流量挤占;额度按合同等级区分。
- 限流与队列如何配合?答:接口限流拒绝超出部分,可异步化的重任务投递队列削峰;限流阈值按接口容量压测设定。
06.5.4.11-018 客户端如何携带认证凭证,Cookie 与 Header 有何差异?
一句话结论
令牌形态通过 Authorization: Bearer <token> 请求头携带;SPA 形态通过 Cookie 自动携带,前端需开启 withCredentials 并保证域与 SameSite 配置正确;两种方式不混用。
概念解释
Header 令牌适合跨端与第三方,由前端主动附加;Cookie 由浏览器自动管理,受 SameSite、Secure、HttpOnly 策略约束。跨域 Cookie 还需 CORS 允许凭证。
原理流程
- 令牌客户端在每个请求头附加 Bearer。
- SPA 浏览器在同站/允许域下自动带 Cookie。
- 跨域请求前端配置携带凭证,服务端 CORS 放行凭证。
- 服务端 guard 按对应来源解析。
代码或图示
// Header 形式
// Authorization: Bearer 83f4...(明文只在请求中出现)
// 前端跨域携带 Cookie(示意配置,具体在前端框架层)
// fetch(url, { credentials: 'include' })
常见误区
- Cookie 站点请求忘记 withCredentials:浏览器不发 Cookie,表现为未登录。
- 令牌写入 HttpOnly Cookie 又同时读 localStorage:两套存储策略冲突,按选定形态统一。
追问
- HTTPS 下 Cookie 标记哪些属性?答:生产环境 Secure、HttpOnly、SameSite 按域场景设置;具体属性由会话配置统一控制。
- Bearer 令牌放在 URL 查询参数可以吗?答:不建议,URL 会进访问日志与历史记录,凭证应走请求头。
06.5.4.11-019 认证相关的安全要点有哪些?
一句话结论
最小权限签发能力、令牌短有效期与可吊销、HTTPS 传输、密钥安全存储、登录限速与防爆破、令牌不落日志、授权回调严格校验、定期轮换密钥与令牌;客户端密钥只存后端。
概念解释
安全链条覆盖传输、存储、签发、使用、吊销各环节:任何一环暴露都可能导致凭证泄露。开放平台还需校验 state、redirect_uri 与客户端身份。
原理流程
- 签发时按最小能力与短过期生成令牌。
- 全链路 HTTPS,防止凭证被窃听。
- 客户端密钥服务端保存,日志脱敏。
- 泄露怀疑时吊销令牌并轮换密钥,监控异常调用。
代码或图示
// 日志中只记录令牌前缀,不记录明文
logger()->info('token issued', [
'user_id' => $user->id,
'token_prefix' => Str::before($token->plainTextToken, '|'),
]);
常见误区
- 把 client_secret 或令牌提交到前端打包产物:打包后可被反编译提取。
- 长期不过期且无吊销入口:设备丢失后风险无法收敛。
追问
- 登录接口如何防暴力破解?答:按 IP 与账号维度限流,失败次数锁定;配合验证码或 MFA 按安全等级选择。
- 授权码 state 作用是什么?答:绑定前端会话与授权请求,回调时比对 state,防止跨站请求伪造授权。
06.5.4.11-020 认证排查的常见路径是什么?
一句话结论
401 先区分未携带凭证、令牌无效/过期、guard 不匹配;403 再区分能力/scope 不足、角色权限不足、数据越权;沿请求头 → guard 配置 → 令牌记录 → 用户与权限表逐层核对。
概念解释
认证问题分三层:身份识别失败(401)、凭证边界不足(403 能力层)、业务权限不足(403 角色/数据层)。排查时不要把所有 403 都归为令牌问题。
原理流程
- 确认请求实际携带的凭证类型(Header/Cookie)。
- 核对路由中间件 guard 与配置 provider。
- 查表确认令牌存在、未过期、未吊销、能力匹配。
- 再进入业务层校验角色与数据归属。
代码或图示
// 调试输出(仅本地/测试环境):当前用户与令牌状态
dump([
'guard' => auth()->guard()->name ?? null,
'user' => auth()->id(),
'abilities' => auth()->user()?->currentAccessToken()?->abilities ?? [],
]);
常见误区
- 看到 401 直接改宽松中间件:可能是 guard 配置或令牌表问题,应先定位根因。
- 测试环境放宽校验后带到生产:调试代码与放宽配置必须随环境隔离移除。
追问
- 多实例下 401 偶发如何排查?答:检查会话/令牌存储是否共享、Cookie 域配置、负载均衡粘性需求;会话驱动不共享会导致随机未登录。
- 如何写认证层自动化测试?答:actingAs 模拟用户,分别断言带令牌、不带令牌、能力不足的响应;覆盖 SPA 会话与令牌两类入口。