Go http.Request.BasicAuth 解析 Authorization 凭据的校验流程

在内部管理接口、临时运维入口或兼容旧客户端时，Go 服务经常会收到带 Authorization 的 Basic Authentication 请求。这个场景最容易混淆的一点是：能解析出用户名和密码，只代表请求格式正确，并不代表用户已经登录成功。http.Request.BasicAuth 正好把这两个层次拆开，返回用户名、密码和一个格式判断值。

先用 ok 判断请求是否真的是可解析的 Basic 凭据，再比较账号密码；失败统一返回 401，并只在 HTTPS 上传输，日志中不要记录原始凭据。

先把 BasicAuth 的三个返回值分开看

官方 net/http 文档把 BasicAuth 定义为从请求的 Authorization 头读取 Basic Authentication 提供的用户名和密码。代码不需要自己截取字符串、解码 Base64 或猜测空值，直接调用方法即可。

func basicCredentials(r *http.Request) (string, string, bool) {
    username, password, ok := r.BasicAuth()
    return username, password, ok
}

这里的 ok 是解析结果：没有 Authorization 头、认证方案不是 Basic，或凭据格式无法解析时，应按失败处理。用户名和密码可能是空字符串，所以不能只写 if username != "" 来判断是否带认证。

把解析成功和登录通过分成两次判断

实际 Handler 中建议保持两层判断。第一层确认协议格式，第二层再把解析出的值与服务端配置或安全存储中的账号信息比较。这样能避免把畸形请求误判成“密码错误”，也不会把认证解析和业务授权混在一起。

func admin(w http.ResponseWriter, r *http.Request) {
    username, password, ok := r.BasicAuth()
    if !ok || username != "operator" || password != "replace-me" {
        w.Header().Set("WWW-Authenticate", `Basic realm="admin"`)
        http.Error(w, "unauthorized", http.StatusUnauthorized)
        return
    }

    w.WriteHeader(http.StatusNoContent)
}

示例中的固定字符串只用于说明判断位置，生产环境应从安全配置读取，并用恒定时间比较或成熟的认证组件处理敏感凭据。认证通过后还要继续判断当前用户是否有访问某个资源的权限，BasicAuth 本身不会替你完成授权。

401 响应、HTTPS 与日志脱敏要一起处理

未认证请求通常返回 401，并通过 WWW-Authenticate 告诉客户端需要哪种认证方案。不要把 403 当作所有失败的统一结果：401 表示尚未提供有效认证，403 更适合表达身份已知但没有权限。

Basic Authentication 只是对用户名和密码做编码，不提供加密。Request.SetBasicAuth 的官方说明也明确提醒，通常应当配合 HTTPS 使用。服务端还要注意反向代理是否正确转发 Authorization 头，并在访问日志、错误日志、链路追踪字段中删除或遮盖该头以及解析后的密码。

几个容易踩坑的边界

• 不要把 ok 当成登录成功。它表示头部能否按 Basic Authentication 解析，账号是否存在、密码是否匹配仍是业务判断。
• 不要自行拼接解码逻辑。手写 Base64 解码容易遗漏认证方案、空凭据和错误头部等边界，优先使用标准库方法。
• 不要在 HTTP 上发送密码。如果入口没有 TLS，网络上的观察者可以直接获得可复用的凭据。
• 不要记录完整 Authorization。调试时最多记录认证方案和脱敏后的用户名，密码和 Base64 内容都应排除。

相关问答

BasicAuth 返回 ok=true 就一定能访问接口吗？

不一定。ok 只说明请求头可按 Basic Authentication 解析；还必须完成账号、密码和资源权限的校验。

为什么失败响应要设置 WWW-Authenticate？

它让客户端知道服务端要求的认证方案和 realm。对于 Basic Authentication，通常与 401 一起返回，便于客户端重新发起带凭据的请求。

把 BasicAuth 当作“解析器”而不是“登录系统”，Handler 的责任会更清楚：标准库负责拆出凭据，业务代码负责验证身份，HTTPS 和日志策略负责保护凭据，授权代码再决定用户能做什么。