Go / 系统课时
处理 Bearer 凭据
处理 Bearer 凭据
Bearer 凭据进入 HTTP 服务后,需要把头部解析、身份认证、权限判断和日志脱敏放在同一条安全边界上。本篇用一个可运行的 Go 示例明确 400、401 与 403 的分工,并验证重复头、错误方案、无效凭据和无权限请求的处理结果。
学习目标
- 校验
Authorization的 Bearer 方案与基本格式 - 区分格式错误、未认证与已认证但权限不足的 HTTP 状态
- 避免在日志、错误信息和追踪字段中泄漏 Bearer 凭据
明确认证与授权边界
Authorization: Bearer <token> 只表示客户端提交了一份凭据,不能据此认为认证成功。入口应依次完成头部检查、凭据验证和权限判断,任何阶段都不应把原始 token 写入响应或日志。
| 情况 | HTTP 状态 | 处理原则 |
|---|---|---|
| 未提供可接受的认证信息 | 401 Unauthorized | 返回 Bearer challenge,但不必声明具体 token 错误 |
Bearer 请求本身格式错误或出现重复 Authorization 头 |
400 Bad Request | 拒绝歧义请求,可声明 error="invalid_request" |
| Bearer 凭据无效或已过期 | 401 Unauthorized | 可声明 error="invalid_token" |
| 凭据有效,但主体缺少所需权限 | 403 Forbidden | 可声明 error="insufficient_scope" 与所需 scope |
| 凭据有效且权限满足 | 2xx | 继续进入业务处理 |
这里把“没有可接受的认证信息”和“提交了无效 Bearer token”都归入未认证场景,因此使用 401;只有身份已经可信确认后,权限不足才使用 403。重复头或 Bearer 语法本身有歧义时则先按坏请求拒绝,不进入 token 验证。

用一个中间件完成判定
下面程序只用 Go 标准库和 net/http/httptest 模拟两种有效凭据:reader-token 只有读权限,writer-token 有写权限。解析器拒绝重复的 Authorization 头与格式错误的 Bearer 值;测试表同时覆盖缺失凭据、错误方案、无效 token、权限不足和成功请求。
package main
import (
"fmt"
"net/http"
"net/http/httptest"
"strings"
)
type parseState int
const (
bearerOK parseState = iota
bearerMissing
bearerWrongScheme
bearerMalformed
bearerDuplicate
)
func parseBearer(r *http.Request) (string, parseState) {
values := r.Header.Values("Authorization")
switch len(values) {
case 0:
return "", bearerMissing
case 1:
// 继续解析唯一的 Authorization 值。
default:
return "", bearerDuplicate
}
fields := strings.Fields(values[0])
if len(fields) == 0 {
return "", bearerMalformed
}
if !strings.EqualFold(fields[0], "Bearer") {
return "", bearerWrongScheme
}
if len(fields) != 2 || fields[1] == "" {
return "", bearerMalformed
}
// 方案名大小写不敏感,但凭据值必须保持原样。
return fields[1], bearerOK
}
func authenticate(token string) (scope string, ok bool) {
switch token {
case "reader-token":
return "read", true
case "writer-token":
return "write", true
default:
return "", false
}
}
type writeGuard struct {
next http.Handler
}
func (g writeGuard) ServeHTTP(w http.ResponseWriter, r *http.Request) {
token, state := parseBearer(r)
switch state {
case bearerMissing, bearerWrongScheme:
w.Header().Set("WWW-Authenticate", `Bearer realm="api"`)
fmt.Println("auth=failed reason=missing_or_unsupported_bearer")
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
case bearerMalformed, bearerDuplicate:
w.Header().Set("WWW-Authenticate", `Bearer realm="api", error="invalid_request"`)
fmt.Println("auth=failed reason=invalid_bearer_request")
http.Error(w, "invalid request", http.StatusBadRequest)
return
}
scope, ok := authenticate(token)
if !ok {
w.Header().Set("WWW-Authenticate", `Bearer realm="api", error="invalid_token"`)
fmt.Println("auth=failed reason=invalid_token")
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
if scope != "write" {
w.Header().Set(
"WWW-Authenticate",
`Bearer realm="api", error="insufficient_scope", scope="write"`,
)
fmt.Printf("auth=denied scope=%s\n", scope)
http.Error(w, "forbidden", http.StatusForbidden)
return
}
// 日志只记录认证结果与低敏权限信息,不记录 token。
fmt.Println("auth=ok scope=write")
g.next.ServeHTTP(w, r)
}
func requireWrite(next http.Handler) http.Handler {
return writeGuard{next: next}
}
type requestCase struct {
name string
headerValues []string
}
func main() {
business := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
fmt.Fprint(w, "updated")
})
handler := requireWrite(business)
cases := []requestCase{
{name: "missing"},
{name: "wrong-scheme", headerValues: []string{"Basic abc"}},
{name: "duplicate", headerValues: []string{"Bearer writer-token", "Bearer writer-token"}},
{name: "invalid-token", headerValues: []string{"Bearer expired-token"}},
{name: "no-permission", headerValues: []string{"Bearer reader-token"}},
{name: "allowed", headerValues: []string{"Bearer writer-token"}},
}
for _, c := range cases {
req, err := http.NewRequest(http.MethodPost, "http://example.test/resource", nil)
if err != nil {
panic(err)
}
for _, value := range c.headerValues {
req.Header.Add("Authorization", value)
}
rr := httptest.NewRecorder()
handler.ServeHTTP(rr, req)
fmt.Printf("%s -> %d %s\n", c.name, rr.Code, strings.TrimSpace(rr.Body.String()))
}
}预期输出
auth=failed reason=missing_or_unsupported_bearer
missing -> 401 unauthorized
auth=failed reason=missing_or_unsupported_bearer
wrong-scheme -> 401 unauthorized
auth=failed reason=invalid_bearer_request
duplicate -> 400 invalid request
auth=failed reason=invalid_token
invalid-token -> 401 unauthorized
auth=denied scope=read
no-permission -> 403 forbidden
auth=ok scope=write
allowed -> 200 updated这里的 authenticate 只是教学替身。真实服务应替换为可信的凭据验证逻辑,例如校验签名、有效期、发行方和受众,或调用统一认证组件。只要身份仍未被可信确认,失败结果就属于认证失败;确认身份后才进入权限判断。
阻止凭据进入可观测性系统
最常见的泄漏点并不是业务代码主动打印 token,而是访问日志、错误包装或 tracing 自动采集整个请求头。生产环境应把 Authorization、Cookie 等字段视为默认禁止记录的敏感数据。
访问日志可以保留请求方法、路由、状态码、请求 ID,以及认证成功后允许暴露的稳定主体 ID。认证失败时记录 invalid_bearer_request、invalid_token 这类低敏原因即可,也不要通过打印 token 的前后几位来辅助排查。
错误对象、span attribute 和 baggage 应遵循同样的边界。需要关联一次失败请求时使用请求 ID,而不是复制原始 Authorization 值。
收紧凭据入口
Bearer 方案名可以按大小写不敏感处理,但凭据值必须原样交给认证系统验证。解析失败时不要继续从查询参数、表单或自定义头中寻找同一凭据,否则会产生多来源歧义,并扩大凭据进入 URL、访问日志和监控系统的风险。
稳定的边界应保持单一:入口只接受约定的 Authorization: Bearer ...。格式或重复头造成歧义时先以 400 拒绝;未建立可信身份时返回 401;身份有效但权限不足时返回 403;日志与追踪始终不携带 Bearer 值。这样 HTTP 语义、认证授权和可观测性策略才能保持一致。