Guest Identity Gate:L1 认证、L2 身份类、L3 授权——有效 JWT ≠ 能调一切

Hello,我是小兔大白糖。 产品要冷启动——游客先翻两页资源、再决定要不要注册;网关这边却常把「JWT 签名过了」当成「这人啥都能调」。于是合法 guest token 一路走进聊天、写操作、管理面。写成这篇,给要做 Guest / 匿名身份边界选型 的初中级后端(以及要对齐合同的客户端同学):业界常见的三层拆法与模式对照,不是某家仓库说明书。
说明:文中
guest/registered/verified、HTTP 状态码与伪流程均为教学脱敏示意。不声称任何厂商「官方内部就是这样」。身份类命名各产品不同,合同形状可以对照。
估计阅读时间:9 分钟
目录
为什么现在要关心
有效 token 只证明「凭据有效」,不证明「guest 能调聊天 / 写接口」。
现场里「游客权限炸了」这句话,常常混了三件不同的事:
| 你看到的现象 | 常见真相 |
|---|---|
| 「JWT 验过了,怎么还 403?」 | L1 过了;L2 Identity Gate 在挡 guest |
| 「前端没按钮,接口却被打穿」 | 只藏 UI,没在网关 default-deny |
| 「公开页好好的,挂了 guest token 反而怪」 | Optional JWT:有 claims 仍要过 L2,和「未挂鉴权的公开路由」不是同一合同 |
| 「scopes 写在 token 里了」 | L3 字段存在 ≠ 中间件强制;假装已生效是常见事故源 |
三条硬规则先钉死——删掉机场比喻也能复述给同事:
- L1 认证 ≠ L2 身份类 ≠ L3 授权。
- Guest:default-deny + allowlist;正式用户过 L2 后再谈 L3。
- 公开路由(未挂鉴权)≠「带着 guest JWT 打受保护路由」——后者仍要过 Identity Gate。
问题空间:冷启动与「有 token 就能写」
产品要少量浏览与登录升级;安全合同要防止「合法 guest JWT ≡ 全站业务 API」。
常见失误只有一句话:只验签名与会话,把 guest 与正式用户放进同一批业务 handler。
冷启动本身合理:未登录也能看列表、读详情、走到登录页。危险的是把「能发一张 guest 票」升级成「票上写着谁,谁就能写库、开聊、改配置」。模型层若已有 scopes / ACL 概念却从不在网关强制,等于把授权画在 PPT 上。
后端类比:连接池「能连上」不等于「这根连接有写权限」;线程池「线程还活着」不等于「这任务该进这组 worker」。类比局限:池子解释「准入与配额」;解释不了 OAuth / JWT 字段名与各框架中间件钩子——字段按协议分,分层合同可以通用。
心智模型:机场安检三道
证件真伪是 L1;旅客类型通道是 L2;登机口舱位核对是 L3。参观券默认不能进登机口。
入境旅客
│
▼
L1 证件 / 登机牌验真 ──失败──► 拒入(类比 401)
│通过
▼
L2 通道分流:贵宾 / 普通 / 参观券(guest)
│
├─ 正式旅客 ──────────────────────────────┐
│ │
└─ 参观券:仅白名单柜台可办 ──未命中──► 拒入(类比 403)
│命中 │
▼ ▼
L3 舱位 / 登机口核对(可先 Nop,但别假装已查)──► 登机- L1 Authentication(认证):凭据在不在、签名与会话有没有过期。失败 → 通常 401。
- L2 Identity class(身份类):你是 guest、registered、还是更强身份。Guest:默认拒绝,仅 method + path 命中 allowlist(白名单) 才放行。
- L3 Authorization(授权):role / scope / 资源 ACL。可以分阶段上;预留接口 + Nop 起步可以,把「token 里有 scopes」当成已强制不行。
类比局限:机场安检解释「先验人、再分通道、再核舱位」;解释不了具体 JWT claim 名、网关框架 API、以及各司法辖区对匿名追踪的合规边界——那些另开合同。设备侧「认出游客」是另一层信号,见同系列 设备指纹分层;别和本篇的网关 Identity Gate 揉成一句「指纹过了就能写」。
硬规则:三层别混
过 L1 只说明「这张票真」;guest 默认不能进业务登机口,除非柜台在白名单上。
| 层 | 回答的问题 | 失败时常见语义 |
|---|---|---|
| L1 | 凭据有效吗? | 401:未认证 / 票无效或过期 |
| L2 | 你是哪类旅客?guest 是否命中允许的 method+path? | 403 + 稳定错误码:已认出身份,但本接口不允许 |
| L3 | 对这个资源,你的 role/scope 够不够? | 仍多是 403;与 L2 用不同 errno / 文案区分更易排障 |
补充边界(教学合同,不是某框架文档原文):
- registered / verified:通常直接过 L2,再进 L3(哪怕 L3 暂时是 Nop)。
- guest:default-deny;冷启动读、登录升级相关路径必须显式进 allowlist,否则产品「能逛」与网关「全拒」会打架。
- 未挂鉴权的公开路由:跳过 L1/L2——它本来就对外。
- 挂了 Optional JWT 的路由:无 token 可按公开行为;一旦带上有效 guest claims,仍要过 L2。公开与「挂了票的 guest」不是同一合同。
Allowlist 键建议:HTTP method + 规范化 path(是否去尾斜杠、是否大小写折叠,要写死并测)。键合同漂移 = 文档绿灯、运行时红灯。
四种模式对照
短期推荐 B;L3 预留再演进。禁止只靠 D(前端藏按钮)。
| 模式 | 做法 | 代价 / 副作用 | 适用 |
|---|---|---|---|
| A. 只做 L1 | 有效 JWT 一律进业务 API | guest 权限过宽;事故面最大 | 仅内网 demo |
| B. L1 + L2 default-deny allowlist | guest 白名单;正式用户过 L2 | 白名单要维护;冷启动路径必须列入 | 冷启动 + guest 产品的主流默认 |
| C. 上 L3 scopes / ACL | 按资源与动作细授权 | 实现、测试、文档成本高 | 权限模型变复杂后 |
| D. 只藏前端按钮 | UI 不展示敏感入口 | 直接打 API 即可绕过 | 不当生产默认 |
没有「最佳实践」空喊——只谈账单:
- B 用「维护一份 method+path 表」换「guest 默认进不了写/聊」。表漏了,冷启动挂;表松了,权限回 A。
- C 解决的是「同一身份类内部谁能碰哪类资源」;解决不了「忘了强制」——接口在、中间件空转,等于没上。
- A + D 组合最常见:前端看起来乖,抓包一打就穿。
- 推荐节奏:先 B,L3 接口预留、Nop 显式标注;再按资源风险演进 C。 禁止「token 里写了 scopes」当对外叙事。
与 OAuth 收口选型同理:渠道合同先钉死,再谈字段——见 OAuth 回调 HTML 桥页。
契约示意(教学)
L1 失败 401;L2 guest 未命中 403 + 稳定 errno,方便 FE 引导登录。
请求进入网关
│
├─ 路由未挂鉴权 ──────────────────────────────► handler(公开合同)
│
└─ 路由挂了 Required / Optional 鉴权
│
▼
L1:无/无效 token? ──是──► 401
│否(已有有效 claims)
▼
L2:identity == guest?
│是 │否(registered / verified …)
▼ ▼
allowlist(method, path) L3(可为 Nop,但要诚实)
│未命中 → 403 + errno
│命中
▼
L3 → handler反例(不要照着做):
Optional:无 token 当公开;有 guest token 却跳过 L2 // 有票反而更宽或行为未定义
白名单写「将来可能公开」的 path,运行时却未挂中间件 // 文档与运行时漂移
JWT 塞满 scopes,网关从不读 // L3 假装已生效
guest 拒绝回 401 // 客户端分不清「请登录」与「登录过期」状态码为什么要分:
| 语义 | 建议 | 客户端动作 |
|---|---|---|
| 没票 / 票坏了 / 过期 | 401 | 清会话、走登录或刷新 |
| 认出是 guest,本接口不允许 | 403 + 稳定业务错误码 | 引导注册/登录,不必当成「token 坏了」死循环刷新 |
日志与对外文案仍守 PII 红线:只记 request_id、身份类、是否命中白名单,不回传完整 token——见 PII 别进 Logs/URL/Error。
全文无大段实现墙;删掉伪流程后,上表与三条硬规则仍应能独立复述。
常见坑
多数事故来自「层混了」和「Optional 合同没写清」,不是 JWT 库抽风。
| 坑 | 为什么危险 | 怎么改 |
|---|---|---|
| Optional JWT:有 guest claims 却不过 gate | 有票路径与无票路径权限不一致,难测 | 有有效 claims → 一律过 L2 |
| 白名单写「计划公开」却未挂中间件 | 文档绿灯、运行时红灯或相反 | 白名单只收录真实挂着鉴权的 guest 可达路径;公开路由另册 |
| L3 scopes 进 JWT 但从不强制 | 审计以为已授权,攻击面仍按 L1 | Nop 要显式;上线叙事对齐「尚未强制」 |
| guest 拒绝用 401 | FE 当过期狂刷;与真过期无法区分 | guest 不允许 → 403 + 稳定 errno |
| allowlist 不规范化 path | /foo 与 /foo/ 一个过一个炸 | 键合同写死:method + 规范化 path,加单测 |
| 只靠前端藏按钮 | 直接调 API 绕过 | 网关 B 为底线;UI 是体验,不是授权 |
选型结论
- 分清三层: L1 认证、L2 身份类、L3 授权;有效 JWT ≠ guest 能调一切。
- Guest 走 default-deny + allowlist; 冷启动与登录升级路径必须显式列入。
- guest 拒绝用 403 + 稳定错误码; FE 引导登录,勿与 401 过期混用。
- L3 可 Nop 起步,但禁止假装 scopes 已生效。
- Optional 路由:有 claims 仍过 L2; 未挂鉴权的公开路由与「挂了 guest 票的受保护路由」分开写合同。
相关阅读:OAuth 回调收口见 /blog/oauth_callback_html_bridge/;设备指纹分层见 /blog/device_fingerprint_tiers/;日志 / URL 敏感面见 /blog/pii_never_in_logs_urls_errors/。
一句话带走:安检验的是票真不真;参观券默认不能登机——白名单柜台可以办,别把「票验过了」当成「舱位随便坐」。