代码术语:bearer

差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

后一修订版
前一修订版
代码术语:bearer [2026/10/13 22:44] – 创建 张叶安代码术语:bearer [2026/10/13 22:45] (当前版本) – 补充本页思维导图 张叶安
行 1: 行 1:
-1+====== Bearer(持有者令牌) ====== 
 + 
 +**Bearer** 的字面意思是「**持有者 / 持票人**」。''Authorization: Bearer <token>'' 里的 ''Bearer'' 是**认证方案(auth scheme)的名字**,它只宣告一条规则:**谁把这个令牌拿出来,谁就是被授权者**——不记名、不绑定具体的人或客户端,像一张不记名的车票,谁拿着都能上车。 
 + 
 +所以这个词的重点不在「令牌长什么样」,而在于「**持有本身就是全部证明**」。理解了这一点,与 Bearer 有关的所有安全要求(必须 HTTPS、寿命要短、泄露即失窃、必须可撤销)就都是它的直接推论。 
 + 
 +> **一句话**:Bearer 令牌是**不记名凭证**——服务端只验「票是真的」,不问「票本来属于谁」。 
 + 
 +===== 一、字面含义:为什么叫 Bearer ===== 
 + 
 +^ 说法 ^ 含义 ^ 
 +| ''bearer'' | 持有者、持票人(拿票的那个人) | 
 +| 记名票据 | 票上写着名字,只有本人能用,需要额外证明身份 | 
 +| **不记名票据(bearer)** | 票上不写名字,**谁拿来给谁办事** | 
 +| Bearer 令牌 | 电子化的不记名票据:令牌 = 一张完整的票 | 
 + 
 +由此直接推出三条铁律: 
 + 
 +  * **传输必须加密**:令牌被旁观一次,任何人都能立刻冒用,因此规范要求必须走 TLS。 
 +  * **寿命必须短**:不记名意味着泄露后没有第二道门,只能靠「很快失效」把窗口收窄。 
 +  * **必须可撤销**:票丢了要能挂失(撤销 / 轮换),否则泄露期间攻击者一路畅通。 
 + 
 +===== 二、两个容易混的语境 ===== 
 + 
 +''Bearer'' 在代码里主要出现在两个位置,它们是同一件事的两面: 
 + 
 +^ 语境 ^ 出现形式 ^ 说明 ^ 
 +| HTTP 认证方案 | ''Authorization: Bearer <token>'' | RFC 6750 定义的**用法**:凭证放在哪、怎么带 | 
 +| OAuth 2.0 令牌类型 | 令牌响应里的 ''"token_type": "Bearer"'' | RFC 6749 定义的**令牌种类**:这类令牌按上面的方式使用 | 
 + 
 +<code json> 
 +{ 
 +  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", 
 +  "token_type": "Bearer", 
 +  "expires_in": 3600, 
 +  "scope": "orders:read" 
 +} 
 +</code> 
 + 
 +注意:**OAuth2 的 ''token_type'' 决定这个令牌用哪个 scheme 携带**,''Bearer'' 是最常见的那一个。方案名**大小写不敏感**(''bearer'' / ''BEARER'' 等价),但惯例统一写 ''Bearer''。 
 + 
 +===== 三、三种传递方式 ===== 
 + 
 +RFC 6750 只承认三种携带令牌的方式,**同一个请求里只能用一种**: 
 + 
 +^ 方式 ^ 写法 ^ 评价 ^ 
 +| **1. 请求头(推荐)** | ''Authorization: Bearer <token>'' | 标准做法,不落日志、不进浏览器历史 | 
 +| 2. 表单体 | ''access_token=<token>'',''Content-Type: application/x-www-form-urlencoded'' | 只允许 **POST**,仅用于无法设置请求头的场景 | 
 +| 3. URL 查询参数 | ''?access_token=<token>'' | 规范明确**不建议使用**,会经 ''Referer''、历史和日志泄露 | 
 + 
 +<code http> 
 +GET /v1/orders HTTP/1.1 
 +Host: api.example.com 
 +Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 
 +</code> 
 + 
 +补充:令牌的语法在 RFC 6750 里叫 ''b64token''(base64url 字符集,可含 ''-._~+/'' 与若干 ''=''),RFC 9110 起统一改称 **''token68''**。关键词是**令牌内部不允许出现空白字符**——报 ''invalid_token'' 时,先检查是不是复制粘贴混进了换行。 
 + 
 +===== 四、失败时怎么回应 ===== 
 + 
 +Bearer 的错误语义是这套规范里最容易被忽略、也最容易写错的部分: 
 + 
 +<code http> 
 +HTTP/1.1 401 Unauthorized 
 +WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="The access token expired" 
 +</code> 
 + 
 +^ 状态码 ^ 场景 ^ 是否带 error ^ 
 +| **401** | 完全没带凭证(缺头、scheme 不对、格式错) | **不应**带 error,只给 ''WWW-Authenticate: Bearer'',客户端据此发起认证 | 
 +| **401** | 带了凭证但无效(签名错、已过期、已撤销) | 带 ''error="invalid_token"'' | 
 +| **401** | 请求用法不合规(例如同时用两种传递方式、一次带多个令牌) | 带 ''error="invalid_request"'' | 
 +| **403** | 凭证有效,但**权限范围不够** | 带 ''error="insufficient_scope"'',并**应当**附 ''scope="..."'' 告知还缺什么 | 
 + 
 +其中 ''error_description'' 是给人看的,''error_uri'' 指向文档;**客户端的判断逻辑只应依赖 ''error'' 码,不要去解析描述文本**。 
 + 
 +===== 五、和其他 scheme 对照 ===== 
 + 
 +^ scheme ^ 凭证是什么 ^ 每个请求都带用户密码 ^ 能否证明「持有者就是本人」 ^ 
 +| ''Basic'' | ''base64(user:password)'' | 是 | 能(密码本身就是秘密) | 
 +| ''Digest'' | 挑战 nonce + 摘要响应 | 否(用摘要代替明文) | 能 | 
 +| **''Bearer''** | 一个字符串令牌 | 否 | **不能**,只证明「持有」 | 
 +| ''DPoP''(RFC 9449) | Bearer + 客户端密钥签名 | 否 | **能**:令牌绑定密钥,偷走也用不了 | 
 +| ''mTLS'' 绑定令牌(RFC 8705) | Bearer + 客户端证书 | 否 | **能**:令牌绑定证书指纹 | 
 + 
 +这张表的重点是最后两行:**Bearer 的固有弱点是「令牌可被转手使用」**,业界的加固方向就是把它变成**发送者受限令牌(sender-constrained token)**——要么用密钥证明持有(DPoP),要么用证书绑定(mTLS)。 
 + 
 +===== 六、Bearer 令牌 ≠ JWT ===== 
 + 
 +这是实际交流中最常见的概念错位: 
 + 
 +  * **Bearer 说的是「怎么带、怎么验」**(传输与验证方式); 
 +  * **JWT 说的是「令牌内部长什么样」**(一种带签名、可自校验的格式)。 
 + 
 +两者**正交**:Bearer 令牌可以是**不透明字符串**(服务端查到才算数,通常是随机串或 session ID),也可以是 **JWT**(服务端验签即可,不必查库)。反过来,JWT 通常也是**当作 Bearer 令牌**来传递的。格式细节见 [[jwt]]。 
 + 
 +^ 令牌形态 ^ 服务端校验方式 ^ 优点 ^ 代价 ^ 
 +| 不透明令牌 | 查库 / 查 Redis / 自省(RFC 7662) | **可即时撤销**,令牌本身不泄露信息 | 每个请求都要查一次(或需缓存) | 
 +| JWT(自包含) | 验签 + 校验 ''exp'' / ''iss'' / ''aud'' | 无状态、零查询 | **难以即时撤销**,只能等过期或加黑名单 | 
 + 
 +===== 七、代码怎么写 ===== 
 + 
 +命令行调试: 
 + 
 +<code bash> 
 +# 最常用的写法 
 +curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/orders 
 + 
 +# 看 401 的响应头,确认 error 码是否符合规范 
 +curl -i -H "Authorization: Bearer bad-token" https://api.example.com/v1/orders 
 +</code> 
 + 
 +前端:**放进请求头,绝不拼进 URL**。 
 + 
 +<code javascript> 
 +await fetch("/api/orders", { 
 +  headers: { Authorization: `Bearer ${accessToken}` }, 
 +}); 
 +</code> 
 + 
 +服务端:解析 → 校验 → 判范围,三段分开,错误码给对。 
 + 
 +<code javascript> 
 +function bearerAuth(req, res, next) { 
 +  const header = req.get("authorization") || ""; 
 +  const [scheme, token] = header.split(" "); 
 + 
 +  // ① 没带凭证 → 401,且不带 error 
 +  if (!scheme || scheme.toLowerCase() !== "bearer" || !token) { 
 +    res.set("WWW-Authenticate", 'Bearer realm="api"'); 
 +    return res.status(401).json({ error: "unauthorized" }); 
 +  } 
 + 
 +  // ② 带了但无效 → 401 + invalid_token 
 +  const record = lookupToken(token);   // 不透明令牌:查库/Redis 
 +  // 若是不透明令牌改为 verifyJwt(token),并校验 exp / iss / aud 
 +  if (!record || record.revoked || record.expiresAt < Date.now()) { 
 +    res.set("WWW-Authenticate", 'Bearer realm="api", error="invalid_token"'); 
 +    return res.status(401).json({ error: "invalid_token" }); 
 +  } 
 + 
 +  req.auth = { subject: record.subject, scopes: record.scopes }; 
 +  next(); 
 +} 
 + 
 +function requireScope(scope) { 
 +  return (req, res, next) => { 
 +    // ③ 凭证有效但范围不够 → 403 + insufficient_scope 
 +    if (!req.auth.scopes.includes(scope)) { 
 +      res.set("WWW-Authenticate", `Bearer error="insufficient_scope", scope="${scope}"`); 
 +      return res.status(403).json({ error: "insufficient_scope" }); 
 +    } 
 +    next(); 
 +  }; 
 +} 
 + 
 +app.get("/v1/orders", bearerAuth, requireScope("orders:read"), listOrders); 
 +</code> 
 + 
 +===== 八、安全要求都是从哪来的 ===== 
 + 
 +规范的安全考虑可以浓缩成一张表,**每一条都能从「不记名」这个词推导出来**: 
 + 
 +^ 要求 ^ 为什么 ^ 
 +| 全链路 HTTPS | 令牌就是凭证本身,明文传输等于把票递给旁观者 | 
 +| 不要把令牌放 URL | 会进浏览器历史、''Referer''、反向代理与访问日志 | 
 +| 不要把令牌写进日志 / 错误上报 | 日志的可见范围远大于令牌的授权范围 | 
 +| 寿命要短,用 refresh token 换新 | 缩小泄露之后的可用窗口 | 
 +| 支持撤销与轮换 | 不记名凭证丢了,只能靠「挂失」补救 | 
 +| 高价值场景改用发送者受限令牌 | DPoP(RFC 9449)或 mTLS 绑定(RFC 8705),让偷到的令牌用不上 | 
 +| 不要把令牌放进 Cookie | 会成为 CSRF 的目标,见 [[代码术语:一文讲清楚什么是csrf|CSRF]];走请求头天然免疫 | 
 + 
 +===== 九、上线检查清单 ===== 
 + 
 +  * 接口只接受 ''Authorization: Bearer'',且 scheme 判定大小写不敏感 
 +  * 同一请求只允许一种令牌传递方式;走 URL 参数的旧接口已下线 
 +  * 401 / 403 语义正确,401 一定带 ''WWW-Authenticate'' 
 +  * ''error'' 只用规范值:''invalid_request'' / ''invalid_token'' / ''insufficient_scope'' 
 +  * 令牌随机且足够长(不透明令牌建议 ≥ 128 bit 熵),比对用恒定时间函数 
 +  * access token 寿命短(分钟级到小时级),refresh token 支持轮换与重用检测 
 +  * 撤销能即时生效:不透明令牌查库/缓存;JWT 要么短寿命,要么配黑名单 
 +  * 日志、APM、错误上报对令牌脱敏;浏览器端不做长期持久化存储 
 +  * 没有把令牌透传到第三方域名、埋点参数或跳转链接里 
 + 
 +===== 十、常见坑 ===== 
 + 
 +^ 坑 ^ 说明 ^ 
 +| 把 Bearer 当成 JWT | 也可能是完全不透明令牌,校验方式完全不同 | 
 +| 把令牌放 URL query | 规范不建议,且会随 ''Referer'' 与日志到处泄露 | 
 +| 令牌长期存在 ''localStorage'' | XSS 可一次性读走;优先放内存并配合刷新机制 | 
 +| 以为放 ''HttpOnly'' Cookie 就安全 | 防住了偷读,却把 CSRF 的风险换了回来 | 
 +| 401 与 403 混用 | 用 403 表示「令牌无效」,会让客户端反复刷新令牌 | 
 +| 401 不带 ''WWW-Authenticate'' | 不符合规范,客户端不知道用哪种认证方式 | 
 +| 相信客户端上报的 ''scope'' | 权限只认服务端保存的记录,绝不信请求里的自称 | 
 +| 令牌有效期设得很长 | 不记名凭证的寿命就是泄露窗口的宽度 | 
 +| 复制粘贴混进换行 / 空格 | 令牌内不允许空白字符,会直接导致 ''invalid_token'' | 
 + 
 +===== 十一、一句话总结 ===== 
 + 
 +> **Bearer 是「不记名」认证方案:''Authorization: Bearer <token>'' 宣告服务端只验票的真伪、不问持票人是谁;因此传输必须加密、寿命要短、要能撤销——如果要连「谁在持有」一起验,就得上 DPoP 或 mTLS 绑定。** 
 + 
 +===== 参考 ===== 
 + 
 +  * RFC 6750 —— [[https://www.rfc-editor.org/rfc/rfc6750.html|OAuth 2.0 Bearer Token 用法(本文主要依据)]] 
 +  * RFC 6749 —— [[https://www.rfc-editor.org/rfc/rfc6749.html|OAuth 2.0 授权框架(''token_type'' 的来源)]] 
 +  * RFC 9110 —— [[https://www.rfc-editor.org/rfc/rfc9110.html|HTTP Semantics(''Authorization'' 头与 ''token68'' 语法)]] 
 +  * RFC 9449 —— [[https://www.rfc-editor.org/rfc/rfc9449.html|DPoP:证明持有(发送者受限令牌)]] 
 +  * RFC 8705 —— [[https://www.rfc-editor.org/rfc/rfc8705.html|mTLS 客户端证书绑定令牌]] 
 +  * RFC 7662 —— [[https://www.rfc-editor.org/rfc/rfc7662.html|令牌自省(Introspection)]] 
 +  * RFC 7009 —— [[https://www.rfc-editor.org/rfc/rfc7009.html|令牌撤销(Revocation)]] 
 +  * MDN —— [[https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Authorization|Authorization 请求头]] 
 + 
 +相关:[[jwt|JWT]] · [[代码术语:authorization|Authorization]] · [[代码术语:一文讲清楚什么是csrf|CSRF]] · [[代码术语:payload|payload]] · [[代码术语:exp|exp]] 
 + 
 +---- 
 + 
 +返回:[[代码术语]] 
 + 
 +```mdk height=560 color=#4f46e5 
 +# Bearer 持有者令牌 
 +## 字面含义 
 +- bearer = 持票人 
 +- 不记名凭证:谁拿来谁能用 
 +- 令牌本身就是全部证明 
 +- 推论:必须 HTTPS、寿命短、可撤销 
 +## 两个语境 
 +- HTTP scheme:Authorization: Bearer <token> 
 +- OAuth2 token_type: "Bearer" 
 +- 方案名大小写不敏感 
 +## 三种传递方式 
 +- 请求头(推荐) 
 +- 表单体:只允许 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 
 +- 令牌有效期过长 
 +- 复制粘贴混进换行空格 
 +``` 

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • 代码术语/bearer.1791902644.txt.gz
  • 最后更改: 2026/10/13 22:44
  • 由 张叶安