WebSocket 连接中使用 JWT Token 进行授权的正确实践

花韻仙語 2026-01-13 00:00:00 次阅读

websocket 客户端需将 jwt token 通过 `authorization: bearer ` 请求头传递，而非 url 查询参数；服务端（如 go 实现）默认仅从请求头或表单字段解析 token，不自动读取查询字符串中的 `access_token`。

在基于 WebSocket 的认证场景中，常见误区是将 JWT Token 直接拼入 WebSocket 连接 URL 的查询参数（如 ?token=xxx 或 ?access_token=xxx），但标准 JWT 认证中间件（如 github.com/dgrijalva/jwt-go）默认不解析 URL 查询参数中的 token。其验证逻辑严格遵循 RFC 6750 规范，优先检查 Authorization 请求头（格式为 Bearer ），其次尝试解析 multipart/form-data 或 application/x-www-form-urlencoded 表单中的 access_token 字段——而 WebSocket 握手请求（HTTP Upgrade）不包含请求体（body），因此表单解析实际无效，最终导致 ErrNoTokenInRequest。

✅ 正确做法：通过 WebSocket 客户端显式设置 Authorization 请求头。

以 Python 客户端为例（使用 websocket-client 库）：

from websocket import create_connection

def test_auth_token(token, ip, port, uuid):
    url = f"ws://{ip}:{port}/{uuid}"
    # 关键：传入 header 列表，添加 Authorization 头
    headers = [f"Authorization: Bearer {token}"]
    conn = create_connection(url, header=headers)
    try:
        result = conn.recv()
        print("Connection successful:", result)
        assert result is not None
    finally:
        conn.close()

⚠️ 注意事项：

WebSocket 握手是 HTTP 协议的 GET 请求，但不支持发送请求体，因此无法使用 POST + body 传 token；
查询参数（如 ?access_token=...）虽能被服务端 req.URL.Query().Get("access_token") 手动获取，但 jwt-go 的 ParseFromRequest 不会自动读取它——你必须自行提取并调用 jwt.Parse()；
若必须使用查询参数（如兼容旧客户端），应在 Go 服务端手动增强解析逻辑：

// 替代方案：扩展 token 提取逻辑（在 ParseFromRequest 前）
func getTokenFromRequest(req *http.Request) (string, error) {
    // 1. Header 优先
    if auth := req.Header.Get("Authorization"); auth != "" && strings.HasPrefix(strings.ToLower(auth), "bearer ") {
        return strings.TrimSpace(auth[7:]), nil
    }
    // 2. 查询参数兜底
    if tok := req.URL.Query().Get("access_token"); tok != "" {
        return tok, nil
    }
    return "", errors.New("no token found in header or query")
}

? 总结：
JWT 授权应遵循标准化传输方式——Authorization: Bearer 是 WebSocket 认证最可靠、最易集成的方案。避免依赖查询参数，既符合安全最佳实践（防止 token 泄露到日志/代理记录），也与主流 JWT 库行为一致。服务端无需修改即可兼容，客户端只需一行 header 配置即可解决认证失败问题。