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

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

Hello,我是小兔大白糖。 产品要冷启动——游客先翻两页资源、再决定要不要注册;网关这边却常把「JWT 签名过了」当成「这人啥都能调」。于是合法 guest token 一路走进聊天、写操作、管理面。写成这篇,给要做 Guest / 匿名身份边界选型 的初中级后端(以及要对齐合同的客户端同学):业界常见的三层拆法与模式对照,不是某家仓库说明书。

说明:文中 guest / registered / verified、HTTP 状态码与伪流程均为教学脱敏示意。不声称任何厂商「官方内部就是这样」。身份类命名各产品不同,合同形状可以对照。

估计阅读时间:9 分钟

L1 认证、L2 身份类、L3 授权三层门禁
L1 认证、L2 身份类、L3 授权三层门禁 · 点击查看 SVG 原图

目录


为什么现在要关心

有效 token 只证明「凭据有效」,不证明「guest 能调聊天 / 写接口」。

现场里「游客权限炸了」这句话,常常混了三件不同的事:

你看到的现象常见真相
「JWT 验过了,怎么还 403?」L1 过了;L2 Identity Gate 在挡 guest
「前端没按钮,接口却被打穿」只藏 UI,没在网关 default-deny
「公开页好好的,挂了 guest token 反而怪」Optional JWT:有 claims 仍要过 L2,和「未挂鉴权的公开路由」不是同一合同
「scopes 写在 token 里了」L3 字段存在 ≠ 中间件强制;假装已生效是常见事故源

三条硬规则先钉死——删掉机场比喻也能复述给同事:

  1. L1 认证 ≠ L2 身份类 ≠ L3 授权。
  2. Guest:default-deny + allowlist;正式用户过 L2 后再谈 L3。
  3. 公开路由(未挂鉴权)≠「带着 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 / 文案区分更易排障

补充边界(教学合同,不是某框架文档原文):

  1. registered / verified:通常直接过 L2,再进 L3(哪怕 L3 暂时是 Nop)。
  2. guest:default-deny;冷启动读、登录升级相关路径必须显式进 allowlist,否则产品「能逛」与网关「全拒」会打架。
  3. 未挂鉴权的公开路由:跳过 L1/L2——它本来就对外。
  4. 挂了 Optional JWT 的路由:无 token 可按公开行为;一旦带上有效 guest claims,仍要过 L2。公开与「挂了票的 guest」不是同一合同。

Allowlist 键建议:HTTP method + 规范化 path(是否去尾斜杠、是否大小写折叠,要写死并测)。键合同漂移 = 文档绿灯、运行时红灯。


四种模式对照

短期推荐 B;L3 预留再演进。禁止只靠 D(前端藏按钮)。

模式做法代价 / 副作用适用
A. 只做 L1有效 JWT 一律进业务 APIguest 权限过宽;事故面最大仅内网 demo
B. L1 + L2 default-deny allowlistguest 白名单;正式用户过 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 但从不强制审计以为已授权,攻击面仍按 L1Nop 要显式;上线叙事对齐「尚未强制」
guest 拒绝用 401FE 当过期狂刷;与真过期无法区分guest 不允许 → 403 + 稳定 errno
allowlist 不规范化 path/foo 与 /foo/ 一个过一个炸键合同写死:method + 规范化 path,加单测
只靠前端藏按钮直接调 API 绕过网关 B 为底线;UI 是体验,不是授权

选型结论

  1. 分清三层: L1 认证、L2 身份类、L3 授权;有效 JWT ≠ guest 能调一切。
  2. Guest 走 default-deny + allowlist; 冷启动与登录升级路径必须显式列入。
  3. guest 拒绝用 403 + 稳定错误码; FE 引导登录,勿与 401 过期混用。
  4. L3 可 Nop 起步,但禁止假装 scopes 已生效。
  5. Optional 路由:有 claims 仍过 L2; 未挂鉴权的公开路由与「挂了 guest 票的受保护路由」分开写合同。

相关阅读:OAuth 回调收口见 /blog/oauth_callback_html_bridge/;设备指纹分层见 /blog/device_fingerprint_tiers/;日志 / URL 敏感面见 /blog/pii_never_in_logs_urls_errors/。

一句话带走:安检验的是票真不真;参观券默认不能登机——白名单柜台可以办,别把「票验过了」当成「舱位随便坐」。