Go BasicAuth 中间件怎么写：解析失败、空密码和 WWW-Authenticate 的生产边界

给内部管理端加一层 BasicAuth，看起来只需要比对用户名和密码就行。真的上线跑起来之后，问题往往都出在边界场景：请求头不是合法的 Basic 格式时该返回什么，用户名存在但密码为空算不算认证通过，认证失败时要不要带上 WWW-Authenticate，还有日志里会不会把整段 Authorization 直接打出来。

Go 的 Request.BasicAuth() 只负责解析凭据，不负责定义安全策略。生产环境里要明确区分「没有凭据」「凭据格式错误」「凭据不匹配」和「认证通过」四种状态，所有失败场景统一返回 401 并发送 WWW-Authenticate: Basic realm=...，日志只留失败原因和请求标识就够了。

为什么 BasicAuth 不是只比对两个字符串那么简单

Basic 认证把用户名和密码编码进请求头里，典型形态是 Authorization: Basic dXNlcjpwYXNz。它解决的是「客户端怎么把一组凭据传递到服务端」的问题，本身不提供传输加密；没有 HTTPS 的话，编码后的内容很容易被中间链路直接还原出来。

Go 的 r.BasicAuth() 会尝试读取这个头，解码 Base64，再按第一个冒号拆分出用户名和密码。这个方法适合把解析逻辑收拢到一处，但解析成功不代表用户名密码正确，更不代表当前用户有权限访问某个资源。

这里先把四个核心状态拆分开，后面写代码才不会把不同问题揉进同一个分支里：

先写一个只负责认证的中间件

示例代码保护的是 /admin/ 这类内部路径。认证中间件只做四件事：拿到凭据、校验凭据、设置失败响应、把已经确认的用户名交给下游逻辑。它不在这一层判断「能不能删除订单」，这类逻辑属于后续的授权层。

type BasicVerifier func(username, password string) bool

func BasicAuth(realm string, verify BasicVerifier, logf func(reason, path string)) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            username, password, ok := r.BasicAuth()
            if !ok {
                logf("missing_or_malformed", r.URL.Path)
                challenge(w, realm)
                return
            }

            if username == "" || password == "" || !verify(username, password) {
                logf("invalid", r.URL.Path)
                challenge(w, realm)
                return
            }

            ctx := context.WithValue(r.Context(), userKey{}, username)
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

func challenge(w http.ResponseWriter, realm string) {
    w.Header().Set("WWW-Authenticate", `Basic realm="`+realm+`"`)
    http.Error(w, "authentication required", http.StatusUnauthorized)
}

空密码单独做拦截是特意设计的。虽然某些解析结果在语法上是合法的，但内部管理端通常不应该把「用户名存在、密码为空」当成合法凭据。真正落地到用户系统的话，还应该调用专门的密码哈希校验逻辑，不要把明文密码直接放在配置文件或者代码里。

把认证和权限边界分开

认证成功之后，用户名只能说明「你是谁」，不能说明「你能做什么」。比如同一个 /admin/ 下可能有只读报表和删除数据两个操作，授权层要根据用户、角色或者租户的策略继续做判断。

func requireRole(role string, next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        username, _ := r.Context().Value(userKey{}).(string)
        if username == "" || !hasRole(username, role) {
            http.Error(w, "forbidden", http.StatusForbidden)
            return
        }
        next.ServeHTTP(w, r)
    })
}

admin := BasicAuth("internal-admin", verifyUser, auditFailure)
deleteOrder := admin(requireRole("order:delete", http.HandlerFunc(deleteOrderHandler)))

这样 401 和 403 的来源就很清晰了：还没确认身份的时候返回 401，身份已经确认但缺少操作权限的时候返回 403。客户端、网关和监控系统可以据此区分「登录凭据有问题」和「角色配置有问题」两类不同故障。

日志和响应里哪些内容需要做收敛

认证失败值得做审计，但没必要把敏感信息全部记下来。日志至少需要请求 ID、路径、失败分类和时间这几个字段；用户名要不要记录，要看它是不是属于低敏感度的业务标识。完整的 Authorization 头、密码、Base64 解码结果和服务端比对用的秘密信息，都不应该进入普通日志。

对外响应也不要细分出「用户名不存在」和「密码错误」这类提示，这会给攻击者提供账号枚举的有效信号。统一返回 authentication required 就足够让客户端知道下一步应该重新提交凭据，内部日志再保留必要的失败计数即可。

用 httptest 验收五条关键路径

不要只测一条成功请求就完事。用 httptest.NewRecorder 和 httptest.NewRequest 把失败响应的状态码、挑战头、下游逻辑是否被调用这几项一起做核对：

1. 没有 Authorization 头：状态码为 401，挑战头存在，下游逻辑没有被调用。
2. 头部不是合法 Basic 格式：仍返回 401，不会把解码错误的原文返回给客户端。
3. 用户名或密码为空：仍返回 401，不会进入后续业务处理逻辑。
4. 凭据错误：仍返回 401，响应体不会泄露「用户不存在」这类细节。
5. 凭据正确：下游能收到请求上下文里的用户名，授权层可以继续判断角色权限。

最后补一条 HTTPS 检查。BasicAuth 本身不是加密方案，正式环境应该让 TLS 在服务入口或者可信代理层终止，同时确认到后端的链路、管理端地址和健康检查入口，不会把凭据发到错误的主机上。

相关问题：BasicAuth 什么时候该换其他方案

BasicAuth 适合保护公网登录页面吗？

通常不适合。它更适合低频、边界明确的内部工具、临时管理端或者简单探针场景；面向大量用户的系统应该使用会话、短期令牌或者成熟身份平台，补上撤销、过期和多因素认证相关的能力。

没有凭据时一定要返回 401 吗？

对 Basic 认证挑战来说，401 是符合协议语义的清晰选择，同时配合 WWW-Authenticate 告诉客户端当前支持的认证方式。已经确认身份但没有资源权限的时候才用 403。

能不能把用户名放进 URL 里测试？

不建议。URL 可能进入代理记录、浏览器历史和访问日志，调试的时候优先使用请求头，同时在测试日志里确认密码和完整凭据没有被打印出来。

发布前检查清单

• 只在 HTTPS 或者可信内网链路下使用 BasicAuth。
• BasicAuth() 的解析结果经过非空检查和真实凭据校验。
• 认证与授权分层，401 和 403 的语义保持一致稳定。
• 失败响应包含挑战头，但不会泄露账号是否存在。
• 日志不包含密码、Authorization 原文或者解码后的凭据信息。
• 五条 httptest 路径和一条 TLS/代理配置检查都完成复核。

BasicAuth 的代码本身很短，安全边界却不该只停留在「能不能读到用户名密码」的层面。把解析、认证、授权、响应和审计几个环节拆开之后，接口遇到异常时才有稳定的判断依据，后续如果要替换成令牌或者统一身份服务也会更顺畅。