**这是本文档旧的修订版!**
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 定义的令牌种类:这类令牌按上面的方式使用 |
{
"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、历史和日志泄露 |
<code http>
GET /v1/orders HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
</code>
补充:令牌的语法在 RFC 6750 里叫 b64token(base64url 字符集,可含 -.~+/ 时,先检查是不是复制粘贴混进了换行。
===== 四、失败时怎么回应 =====
Bearer 的错误语义是这套规范里最容易被忽略、也最容易写错的部分:
<code http>
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm=“api”, error=“invalidtoken”, errordescription=“The access token expired”
</code>
^ 状态码 ^ 场景 ^ 是否带 error ^
| 401 | 完全没带凭证(缺头、scheme 不对、格式错) | 不应带 error,只给 与若干 =),RFC 9110 起统一改称 invalidtokentoken68。关键词是令牌内部不允许出现空白字符——报 WWW-Authenticate: Bearer,客户端据此发起认证 |
| 401 | 带了凭证但无效(签名错、已过期、已撤销) | 带 error=“invalidtoken” |
| 403 | 凭证有效,但权限范围不够 | 带 |
| 401 | 请求用法不合规(例如同时用两种传递方式、一次带多个令牌) | 带 error=“invalidrequest”error=“insufficient_scope”,并应当附 scope=“…” 告知还缺什么 |
其中 errordescription 指向文档;客户端的判断逻辑只应依赖 是给人看的,errorurierror 码,不要去解析描述文本。
===== 五、和其他 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 + invalidtoken
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=“invalidtoken”');
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 + insufficientscope
if (!req.auth.scopes.includes(scope)) {
res.set(“WWW-Authenticate”, Bearer error="insufficient_scope", scope="${scope}");
return res.status(403).json({ error: “insufficientscope” });
}
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;走请求头天然免疫 |
===== 九、上线检查清单 =====
* 接口只接受 Authorization: Bearer,且 scheme 判定大小写不敏感
* 同一请求只允许一种令牌传递方式;走 URL 参数的旧接口已下线
* 401 / 403 语义正确,401 一定带 WWW-Authenticate
* error 只用规范值:invalidrequest / / invalidtokeninsufficient_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 —— OAuth 2.0 Bearer Token 用法(本文主要依据)
* RFC 6749 —— OAuth 2.0 授权框架(''token_type'' 的来源)
* RFC 9110 —— HTTP Semantics(''Authorization'' 头与 ''token68'' 语法)
* RFC 9449 —— DPoP:证明持有(发送者受限令牌)
* RFC 8705 —— mTLS 客户端证书绑定令牌
* RFC 7662 —— 令牌自省(Introspection)
* RFC 7009 —— 令牌撤销(Revocation)
* MDN —— Authorization 请求头
相关:JWT · Authorization · CSRF · payload · exp
—-
返回:代码术语