差别
这里会显示出您选择的修订版和当前版本之间的差别。
| 后一修订版 | 前一修订版 | ||
| 代码术语:bearer [2026/10/13 22:44] – 创建 张叶安 | 代码术语:bearer [2026/10/13 22:45] (当前版本) – 补充本页思维导图 张叶安 | ||
|---|---|---|---|
| 行 1: | 行 1: | ||
| - | 1 | + | ====== Bearer(持有者令牌) ====== |
| + | |||
| + | **Bearer** 的字面意思是「**持有者 / 持票人**」。'' | ||
| + | |||
| + | 所以这个词的重点不在「令牌长什么样」,而在于「**持有本身就是全部证明**」。理解了这一点,与 Bearer 有关的所有安全要求(必须 HTTPS、寿命要短、泄露即失窃、必须可撤销)就都是它的直接推论。 | ||
| + | |||
| + | > **一句话**:Bearer 令牌是**不记名凭证**——服务端只验「票是真的」,不问「票本来属于谁」。 | ||
| + | |||
| + | ===== 一、字面含义:为什么叫 Bearer ===== | ||
| + | |||
| + | ^ 说法 ^ 含义 ^ | ||
| + | | '' | ||
| + | | 记名票据 | 票上写着名字,只有本人能用,需要额外证明身份 | | ||
| + | | **不记名票据(bearer)** | 票上不写名字,**谁拿来给谁办事** | | ||
| + | | Bearer 令牌 | 电子化的不记名票据:令牌 = 一张完整的票 | | ||
| + | |||
| + | 由此直接推出三条铁律: | ||
| + | |||
| + | * **传输必须加密**:令牌被旁观一次,任何人都能立刻冒用,因此规范要求必须走 TLS。 | ||
| + | * **寿命必须短**:不记名意味着泄露后没有第二道门,只能靠「很快失效」把窗口收窄。 | ||
| + | * **必须可撤销**:票丢了要能挂失(撤销 / 轮换),否则泄露期间攻击者一路畅通。 | ||
| + | |||
| + | ===== 二、两个容易混的语境 ===== | ||
| + | |||
| + | '' | ||
| + | |||
| + | ^ 语境 ^ 出现形式 ^ 说明 ^ | ||
| + | | HTTP 认证方案 | '' | ||
| + | | OAuth 2.0 令牌类型 | 令牌响应里的 ''" | ||
| + | |||
| + | <code json> | ||
| + | { | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | " | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | 注意:**OAuth2 的 '' | ||
| + | |||
| + | ===== 三、三种传递方式 ===== | ||
| + | |||
| + | RFC 6750 只承认三种携带令牌的方式,**同一个请求里只能用一种**: | ||
| + | |||
| + | ^ 方式 ^ 写法 ^ 评价 ^ | ||
| + | | **1. 请求头(推荐)** | '' | ||
| + | | 2. 表单体 | '' | ||
| + | | 3. URL 查询参数 | ''? | ||
| + | |||
| + | <code http> | ||
| + | GET /v1/orders HTTP/1.1 | ||
| + | Host: api.example.com | ||
| + | Authorization: | ||
| + | </ | ||
| + | |||
| + | 补充:令牌的语法在 RFC 6750 里叫 '' | ||
| + | |||
| + | ===== 四、失败时怎么回应 ===== | ||
| + | |||
| + | Bearer 的错误语义是这套规范里最容易被忽略、也最容易写错的部分: | ||
| + | |||
| + | <code http> | ||
| + | HTTP/1.1 401 Unauthorized | ||
| + | WWW-Authenticate: | ||
| + | </ | ||
| + | |||
| + | ^ 状态码 ^ 场景 ^ 是否带 error ^ | ||
| + | | **401** | 完全没带凭证(缺头、scheme 不对、格式错) | **不应**带 error,只给 '' | ||
| + | | **401** | 带了凭证但无效(签名错、已过期、已撤销) | 带 '' | ||
| + | | **401** | 请求用法不合规(例如同时用两种传递方式、一次带多个令牌) | 带 '' | ||
| + | | **403** | 凭证有效,但**权限范围不够** | 带 '' | ||
| + | |||
| + | 其中 '' | ||
| + | |||
| + | ===== 五、和其他 scheme 对照 ===== | ||
| + | |||
| + | ^ scheme ^ 凭证是什么 ^ 每个请求都带用户密码 ^ 能否证明「持有者就是本人」 ^ | ||
| + | | '' | ||
| + | | '' | ||
| + | | **'' | ||
| + | | '' | ||
| + | | '' | ||
| + | |||
| + | 这张表的重点是最后两行:**Bearer 的固有弱点是「令牌可被转手使用」**,业界的加固方向就是把它变成**发送者受限令牌(sender-constrained token)**——要么用密钥证明持有(DPoP),要么用证书绑定(mTLS)。 | ||
| + | |||
| + | ===== 六、Bearer 令牌 ≠ JWT ===== | ||
| + | |||
| + | 这是实际交流中最常见的概念错位: | ||
| + | |||
| + | * **Bearer 说的是「怎么带、怎么验」**(传输与验证方式); | ||
| + | * **JWT 说的是「令牌内部长什么样」**(一种带签名、可自校验的格式)。 | ||
| + | |||
| + | 两者**正交**:Bearer 令牌可以是**不透明字符串**(服务端查到才算数,通常是随机串或 session ID),也可以是 **JWT**(服务端验签即可,不必查库)。反过来,JWT 通常也是**当作 Bearer 令牌**来传递的。格式细节见 [[jwt]]。 | ||
| + | |||
| + | ^ 令牌形态 ^ 服务端校验方式 ^ 优点 ^ 代价 ^ | ||
| + | | 不透明令牌 | 查库 / 查 Redis / 自省(RFC 7662) | **可即时撤销**,令牌本身不泄露信息 | 每个请求都要查一次(或需缓存) | | ||
| + | | JWT(自包含) | 验签 + 校验 '' | ||
| + | |||
| + | ===== 七、代码怎么写 ===== | ||
| + | |||
| + | 命令行调试: | ||
| + | |||
| + | <code bash> | ||
| + | # 最常用的写法 | ||
| + | curl -H " | ||
| + | |||
| + | # 看 401 的响应头,确认 error 码是否符合规范 | ||
| + | curl -i -H " | ||
| + | </ | ||
| + | |||
| + | 前端:**放进请求头,绝不拼进 URL**。 | ||
| + | |||
| + | <code javascript> | ||
| + | await fetch("/ | ||
| + | headers: { Authorization: | ||
| + | }); | ||
| + | </ | ||
| + | |||
| + | 服务端:解析 → 校验 → 判范围,三段分开,错误码给对。 | ||
| + | |||
| + | <code javascript> | ||
| + | function bearerAuth(req, | ||
| + | const header = req.get(" | ||
| + | const [scheme, token] = header.split(" | ||
| + | |||
| + | // ① 没带凭证 → 401,且不带 error | ||
| + | if (!scheme || scheme.toLowerCase() !== " | ||
| + | res.set(" | ||
| + | return res.status(401).json({ error: " | ||
| + | } | ||
| + | |||
| + | // ② 带了但无效 → 401 + invalid_token | ||
| + | const record = lookupToken(token); | ||
| + | // 若是不透明令牌改为 verifyJwt(token),并校验 exp / iss / aud | ||
| + | if (!record || record.revoked || record.expiresAt < Date.now()) { | ||
| + | res.set(" | ||
| + | return res.status(401).json({ error: " | ||
| + | } | ||
| + | |||
| + | req.auth = { subject: record.subject, | ||
| + | next(); | ||
| + | } | ||
| + | |||
| + | function requireScope(scope) { | ||
| + | return (req, res, next) => { | ||
| + | // ③ 凭证有效但范围不够 → 403 + insufficient_scope | ||
| + | if (!req.auth.scopes.includes(scope)) { | ||
| + | res.set(" | ||
| + | return res.status(403).json({ error: " | ||
| + | } | ||
| + | next(); | ||
| + | }; | ||
| + | } | ||
| + | |||
| + | app.get("/ | ||
| + | </ | ||
| + | |||
| + | ===== 八、安全要求都是从哪来的 ===== | ||
| + | |||
| + | 规范的安全考虑可以浓缩成一张表,**每一条都能从「不记名」这个词推导出来**: | ||
| + | |||
| + | ^ 要求 ^ 为什么 ^ | ||
| + | | 全链路 HTTPS | 令牌就是凭证本身,明文传输等于把票递给旁观者 | | ||
| + | | 不要把令牌放 URL | 会进浏览器历史、'' | ||
| + | | 不要把令牌写进日志 / 错误上报 | 日志的可见范围远大于令牌的授权范围 | | ||
| + | | 寿命要短,用 refresh token 换新 | 缩小泄露之后的可用窗口 | | ||
| + | | 支持撤销与轮换 | 不记名凭证丢了,只能靠「挂失」补救 | | ||
| + | | 高价值场景改用发送者受限令牌 | DPoP(RFC 9449)或 mTLS 绑定(RFC 8705),让偷到的令牌用不上 | | ||
| + | | 不要把令牌放进 Cookie | 会成为 CSRF 的目标,见 [[代码术语: | ||
| + | |||
| + | ===== 九、上线检查清单 ===== | ||
| + | |||
| + | * 接口只接受 '' | ||
| + | * 同一请求只允许一种令牌传递方式;走 URL 参数的旧接口已下线 | ||
| + | * 401 / 403 语义正确,401 一定带 '' | ||
| + | * '' | ||
| + | * 令牌随机且足够长(不透明令牌建议 ≥ 128 bit 熵),比对用恒定时间函数 | ||
| + | * access token 寿命短(分钟级到小时级),refresh token 支持轮换与重用检测 | ||
| + | * 撤销能即时生效:不透明令牌查库/ | ||
| + | * 日志、APM、错误上报对令牌脱敏;浏览器端不做长期持久化存储 | ||
| + | * 没有把令牌透传到第三方域名、埋点参数或跳转链接里 | ||
| + | |||
| + | ===== 十、常见坑 ===== | ||
| + | |||
| + | ^ 坑 ^ 说明 ^ | ||
| + | | 把 Bearer 当成 JWT | 也可能是完全不透明令牌,校验方式完全不同 | | ||
| + | | 把令牌放 URL query | 规范不建议,且会随 '' | ||
| + | | 令牌长期存在 '' | ||
| + | | 以为放 '' | ||
| + | | 401 与 403 混用 | 用 403 表示「令牌无效」,会让客户端反复刷新令牌 | | ||
| + | | 401 不带 '' | ||
| + | | 相信客户端上报的 '' | ||
| + | | 令牌有效期设得很长 | 不记名凭证的寿命就是泄露窗口的宽度 | | ||
| + | | 复制粘贴混进换行 / 空格 | 令牌内不允许空白字符,会直接导致 '' | ||
| + | |||
| + | ===== 十一、一句话总结 ===== | ||
| + | |||
| + | > **Bearer 是「不记名」认证方案:'' | ||
| + | |||
| + | ===== 参考 ===== | ||
| + | |||
| + | * RFC 6750 —— [[https:// | ||
| + | * RFC 6749 —— [[https:// | ||
| + | * RFC 9110 —— [[https:// | ||
| + | * RFC 9449 —— [[https:// | ||
| + | * RFC 8705 —— [[https:// | ||
| + | * RFC 7662 —— [[https:// | ||
| + | * RFC 7009 —— [[https:// | ||
| + | * MDN —— [[https:// | ||
| + | |||
| + | 相关:[[jwt|JWT]] · [[代码术语: | ||
| + | |||
| + | ---- | ||
| + | |||
| + | 返回:[[代码术语]] | ||
| + | |||
| + | ```mdk height=560 color=# | ||
| + | # Bearer 持有者令牌 | ||
| + | ## 字面含义 | ||
| + | - bearer = 持票人 | ||
| + | - 不记名凭证:谁拿来谁能用 | ||
| + | - 令牌本身就是全部证明 | ||
| + | - 推论:必须 HTTPS、寿命短、可撤销 | ||
| + | ## 两个语境 | ||
| + | - HTTP scheme:Authorization: | ||
| + | - OAuth2 token_type: " | ||
| + | - 方案名大小写不敏感 | ||
| + | ## 三种传递方式 | ||
| + | - 请求头(推荐) | ||
| + | - 表单体:只允许 POST | ||
| + | - URL 查询参数:不建议使用 | ||
| + | - 同一请求只能用一种 | ||
| + | - 令牌语法 token68,不含空白字符 | ||
| + | ## 错误语义 | ||
| + | - 没带凭证 → 401,不带 error | ||
| + | - 无效或过期 → 401 invalid_token | ||
| + | - 用法不合规 → 401 invalid_request | ||
| + | - 范围不够 → 403 insufficient_scope | ||
| + | - 客户端只看 error 码 | ||
| + | ## 与其他方案对比 | ||
| + | - Basic:每次带密码 | ||
| + | - Digest:nonce + 摘要 | ||
| + | - Bearer:只证明持有 | ||
| + | - DPoP(RFC 9449):密钥绑定 | ||
| + | - mTLS(RFC 8705):证书绑定 | ||
| + | ## Bearer 与 JWT | ||
| + | - Bearer 管怎么带,JWT 管长什么样 | ||
| + | - 两者正交 | ||
| + | - 不透明令牌:可即时撤销,需查库 | ||
| + | - JWT:无状态,难撤销 | ||
| + | ## 安全要求 | ||
| + | - 全链路 HTTPS | ||
| + | - 不放 URL、不进日志 | ||
| + | - 短寿命 + refresh 轮换 | ||
| + | - 支持撤销与挂失 | ||
| + | - 高价值场景用发送者受限令牌 | ||
| + | - 不放 Cookie,避免 CSRF | ||
| + | ## 常见坑 | ||
| + | - 把 Bearer 当成 JWT | ||
| + | - 401 与 403 混用 | ||
| + | - 401 不带 WWW-Authenticate | ||
| + | - 相信客户端上报的 scope | ||
| + | - 令牌有效期过长 | ||
| + | - 复制粘贴混进换行空格 | ||
| + | ``` | ||