====== Bearer(持有者令牌) ====== **Bearer** 的字面意思是「**持有者 / 持票人**」。''Authorization: Bearer '' 里的 ''Bearer'' 是**认证方案(auth scheme)的名字**,它只宣告一条规则:**谁把这个令牌拿出来,谁就是被授权者**——不记名、不绑定具体的人或客户端,像一张不记名的车票,谁拿着都能上车。 所以这个词的重点不在「令牌长什么样」,而在于「**持有本身就是全部证明**」。理解了这一点,与 Bearer 有关的所有安全要求(必须 HTTPS、寿命要短、泄露即失窃、必须可撤销)就都是它的直接推论。 > **一句话**:Bearer 令牌是**不记名凭证**——服务端只验「票是真的」,不问「票本来属于谁」。 ===== 一、字面含义:为什么叫 Bearer ===== ^ 说法 ^ 含义 ^ | ''bearer'' | 持有者、持票人(拿票的那个人) | | 记名票据 | 票上写着名字,只有本人能用,需要额外证明身份 | | **不记名票据(bearer)** | 票上不写名字,**谁拿来给谁办事** | | Bearer 令牌 | 电子化的不记名票据:令牌 = 一张完整的票 | 由此直接推出三条铁律: * **传输必须加密**:令牌被旁观一次,任何人都能立刻冒用,因此规范要求必须走 TLS。 * **寿命必须短**:不记名意味着泄露后没有第二道门,只能靠「很快失效」把窗口收窄。 * **必须可撤销**:票丢了要能挂失(撤销 / 轮换),否则泄露期间攻击者一路畅通。 ===== 二、两个容易混的语境 ===== ''Bearer'' 在代码里主要出现在两个位置,它们是同一件事的两面: ^ 语境 ^ 出现形式 ^ 说明 ^ | HTTP 认证方案 | ''Authorization: Bearer '' | RFC 6750 定义的**用法**:凭证放在哪、怎么带 | | OAuth 2.0 令牌类型 | 令牌响应里的 ''"token_type": "Bearer"'' | RFC 6749 定义的**令牌种类**:这类令牌按上面的方式使用 | { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "scope": "orders:read" } 注意:**OAuth2 的 ''token_type'' 决定这个令牌用哪个 scheme 携带**,''Bearer'' 是最常见的那一个。方案名**大小写不敏感**(''bearer'' / ''BEARER'' 等价),但惯例统一写 ''Bearer''。 ===== 三、三种传递方式 ===== RFC 6750 只承认三种携带令牌的方式,**同一个请求里只能用一种**: ^ 方式 ^ 写法 ^ 评价 ^ | **1. 请求头(推荐)** | ''Authorization: Bearer '' | 标准做法,不落日志、不进浏览器历史 | | 2. 表单体 | ''access_token='',''Content-Type: application/x-www-form-urlencoded'' | 只允许 **POST**,仅用于无法设置请求头的场景 | | 3. URL 查询参数 | ''?access_token='' | 规范明确**不建议使用**,会经 ''Referer''、历史和日志泄露 | GET /v1/orders HTTP/1.1 Host: api.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 补充:令牌的语法在 RFC 6750 里叫 ''b64token''(base64url 字符集,可含 ''-._~+/'' 与若干 ''=''),RFC 9110 起统一改称 **''token68''**。关键词是**令牌内部不允许出现空白字符**——报 ''invalid_token'' 时,先检查是不是复制粘贴混进了换行。 ===== 四、失败时怎么回应 ===== Bearer 的错误语义是这套规范里最容易被忽略、也最容易写错的部分: HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="The access token expired" ^ 状态码 ^ 场景 ^ 是否带 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'' | 无状态、零查询 | **难以即时撤销**,只能等过期或加黑名单 | ===== 七、代码怎么写 ===== 命令行调试: # 最常用的写法 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 前端:**放进请求头,绝不拼进 URL**。 await fetch("/api/orders", { headers: { Authorization: `Bearer ${accessToken}` }, }); 服务端:解析 → 校验 → 判范围,三段分开,错误码给对。 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); ===== 八、安全要求都是从哪来的 ===== 规范的安全考虑可以浓缩成一张表,**每一条都能从「不记名」这个词推导出来**: ^ 要求 ^ 为什么 ^ | 全链路 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 '' 宣告服务端只验票的真伪、不问持票人是谁;因此传输必须加密、寿命要短、要能撤销——如果要连「谁在持有」一起验,就得上 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 - 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 - 令牌有效期过长 - 复制粘贴混进换行空格 ```