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 验证。

Bearer 凭据从解析到授权的处理分支

用一个中间件完成判定

下面程序只用 Go 标准库和 net/http/httptest 模拟两种有效凭据:reader-token 只有读权限,writer-token 有写权限。解析器拒绝重复的 Authorization 头与格式错误的 Bearer 值;测试表同时覆盖缺失凭据、错误方案、无效 token、权限不足和成功请求。

go
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()))
    }
}

预期输出

text
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 语义、认证授权和可观测性策略才能保持一致。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

处理 Bearer 凭据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通