Bearer(持有者令牌)

Bearer 的字面意思是「持有者 / 持票人」。Authorization: Bearer <token> 里的 Bearer 是认证方案(auth scheme)的名字,它只宣告一条规则:谁把这个令牌拿出来,谁就是被授权者——不记名、不绑定具体的人或客户端,像一张不记名的车票,谁拿着都能上车。

所以这个词的重点不在「令牌长什么样」,而在于「持有本身就是全部证明」。理解了这一点,与 Bearer 有关的所有安全要求(必须 HTTPS、寿命要短、泄露即失窃、必须可撤销)就都是它的直接推论。

**一句话**:Bearer 令牌是**不记名凭证**——服务端只验「票是真的」,不问「票本来属于谁」。
说法 含义
bearer 持有者、持票人(拿票的那个人)
记名票据 票上写着名字,只有本人能用,需要额外证明身份
不记名票据(bearer) 票上不写名字,谁拿来给谁办事
Bearer 令牌 电子化的不记名票据:令牌 = 一张完整的票

由此直接推出三条铁律:

  • 传输必须加密:令牌被旁观一次,任何人都能立刻冒用,因此规范要求必须走 TLS。
  • 寿命必须短:不记名意味着泄露后没有第二道门,只能靠「很快失效」把窗口收窄。
  • 必须可撤销:票丢了要能挂失(撤销 / 轮换),否则泄露期间攻击者一路畅通。

Bearer 在代码里主要出现在两个位置,它们是同一件事的两面:

语境 出现形式 说明
HTTP 认证方案 Authorization: Bearer <token> 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 <token> 标准做法,不落日志、不进浏览器历史
2. 表单体 accesstoken=<token>,Content-Type: application/x-www-form-urlencoded | 只允许 POST,仅用于无法设置请求头的场景 | | 3. URL 查询参数 | ?accesstoken=<token> 规范明确不建议使用,会经 Referer、历史和日志泄露
GET /v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

补充:令牌的语法在 RFC 6750 里叫 b64token(base64url 字符集,可含 -.~+/ 与若干 =),RFC 9110 起统一改称 token68。关键词是令牌内部不允许出现空白字符——报 invalidtoken 时,先检查是不是复制粘贴混进了换行。

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=“invalidtoken” | | 401 | 请求用法不合规(例如同时用两种传递方式、一次带多个令牌) | 带 error=“invalidrequest”
403 凭证有效,但权限范围不够 带 error=“insufficient_scope”,并应当附 scope=“…” 告知还缺什么

其中 errordescription 是给人看的,erroruri 指向文档;客户端的判断逻辑只应依赖 error 码,不要去解析描述文本。

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 令牌可以是不透明字符串(服务端查到才算数,通常是随机串或 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;走请求头天然免疫
  • 接口只接受 Authorization: Bearer,且 scheme 判定大小写不敏感
  • 同一请求只允许一种令牌传递方式;走 URL 参数的旧接口已下线
  • 401 / 403 语义正确,401 一定带 WWW-Authenticate
  • error 只用规范值:invalidrequest / invalidtoken / 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 绑定。**

相关:JWT · Authorization · CSRF · payload · exp


返回:代码术语

# 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.txt
  • 最后更改: 2026/10/13 22:45
  • 由 张叶安