Go 内部工具怎么添加 HTTP Basic 认证

给内部工具加 HTTP Basic 认证，核心不是手工拼一段 Base64，而是在服务端读取 Authorization 请求头，在客户端使用 SetBasicAuth。Basic 只是编码，不是加密；即使工具只在内网，也应通过 HTTPS 传输，并把账号密码放在环境变量或密钥系统里。

先拆清 Basic 认证的请求边界

一次请求可以抽象成三层：客户端把用户名和密码放进 Authorization: Basic ...，服务端从请求头解析凭据，TLS 再负责保护这条传输链路。Base64 能还原原文，所以不能把“看不懂字符串”当成安全性。

Go 的 Request.BasicAuth 会在请求使用 HTTP Basic Authentication 时返回用户名、密码和布尔值 ok。ok=false 代表没有得到可用的 Basic 凭据，不能仅靠空用户名或空密码判断认证成功。

在 Go 服务端实现认证中间件

内部工具通常只需要包住少量管理接口。认证失败要返回 401，并带上认证挑战，让客户端知道该接口使用 Basic 方案；认证成功后再把请求交给真正的处理器。

package main

import (
    "crypto/subtle"
    "net/http"
    "os"
)

func basicAuth(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        user, pass, ok := r.BasicAuth()
        wantUser := os.Getenv("INTERNAL_TOOL_USER")
        wantPass := os.Getenv("INTERNAL_TOOL_PASS")

        // 先确认格式，再比较固定长度的凭据，避免把认证失败交给业务处理器。
        if !ok || !sameSecret(user, wantUser) || !sameSecret(pass, wantPass) {
            w.Header().Set("WWW-Authenticate", `Basic realm="internal-tool"`)
            http.Error(w, "需要认证", http.StatusUnauthorized)
            return
        }

        // 只有认证通过后，才进入内部工具的实际路由。
        next.ServeHTTP(w, r)
    })
}

func sameSecret(got, want string) bool {
    // 长度不同直接失败；长度相同时用常量时间比较降低简单时序差异。
    if len(got) != len(want) {
        return false
    }
    return subtle.ConstantTimeCompare([]byte(got), []byte(want)) == 1
}

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/internal/report", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("report ready"))
    })

    // 生产环境应把外层监听替换为 HTTPS 或交给可信反向代理终止 TLS。
    http.ListenAndServe(":8080", basicAuth(mux))
}

这里的比较函数不是 Basic 认证协议的必需部分，而是服务端的一层防护。更重要的是不要把密码写死在源码、错误日志或响应正文里。若账号体系已经由网关统一管理，应用层可以只接收网关传递的已验证身份，不必再叠加一套固定账号。

让 Go 客户端发送认证请求

客户端侧不需要手动拼 Basic base64(user:pass)。SetBasicAuth 会设置标准的 Authorization 头；用户名不能包含冒号，这是标准库文档明确的限制。

package main

import (
    "context"
    "fmt"
    "io"
    "net/http"
    "os"
    "time"
)

func callInternalTool(ctx context.Context) error {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet,
        "https://tool.example.test/internal/report", nil)
    if err != nil {
        return err
    }

    // 凭据来自运行环境，不把口令写进代码或命令参数。
    req.SetBasicAuth(os.Getenv("INTERNAL_TOOL_USER"), os.Getenv("INTERNAL_TOOL_PASS"))

    client := &http.Client{Timeout: 5 * time.Second}
    resp, err := client.Do(req)
    if err != nil {
        return err
    }
    defer resp.Body.Close() // 及时释放连接，便于后续请求复用连接池。

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return err
    }
    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("内部工具返回 %s: %s", resp.Status, string(body))
    }
    fmt.Println(string(body))
    return nil
}

如果服务端返回 401，先检查 URL 是否经过 HTTPS、环境变量是否注入到当前进程，以及服务端是否真的读取了 Authorization 头。不要因为“客户端设置了认证”就假设对端一定接受了它。

上线前检查安全与维护边界

Basic 认证适合低复杂度的内部工具入口，但它没有用户注销、密钥轮换、细粒度角色或单点登录能力。跨公网、多人协作或需要审计时，应优先考虑成熟的身份代理、短期令牌或 OAuth2/OIDC，而不是继续堆叠固定账号。

常见问题

BasicAuth 返回的 ok 为什么是 false？

通常是请求没有合法的 Basic Authorization 头。先检查客户端是否调用了 SetBasicAuth，再确认中间代理没有删除或改写该头。

能不能只设置 Authorization 头，不用 SetBasicAuth？

可以，但需要自行保证编码和边界正确。使用标准库方法更容易保持协议格式一致，也减少重复代码。

内部工具必须使用 HTTPS 吗？

应当使用。Basic 的用户名和密码不是加密数据，HTTPS 是保护它们不被链路观察的基本措施；“内网”不是可靠的加密替代品。

参考：Go net/http Request.BasicAuth、Go net/http Request.SetBasicAuth。