前端接入 JWT 后,用户放了一个周末回来,点击任何按钮都提示登录失效。前端拦截器看到 401 就去刷新令牌,刷新接口也返回 401,拦截器再次触发刷新,页面在请求和 401 之间来回打转,控制台几分钟刷出上千条记录。真正的问题不是令牌过期,而是「过期之后该怎么办」没有定义:哪些 401 该刷新,刷新失败后停在哪个状态,谁负责只刷新一次。

另一个故障更隐蔽。鉴权中间件把当前用户放进上下文,用的是字符串 key "user";后来接入的某个统计中间件也用了 "user",存的是另一套结构。处理函数取值时类型断言失败,直接 panic,或者拿到了错误的用户,把别人的数据返回了出去。字符串 key 没有命名空间,谁都可以覆盖谁。

还有一种常见漏洞:角色判断只写在中间件里,处理函数拿到订单 id 就直接查,完全不看这条订单属于谁。攻击者用自己的合法账号登录,把 URL 里的 id 换成别人的,接口返回 200 和别人的订单。这篇讲三件事:登录时怎么签发令牌、中间件怎么校验并把用户安全地传下去、权限判断为什么必须放在服务层。示例只用 Gin、golang-jwt/jwt/v5 和 bcrypt,不依赖数据库,本机可以完整复现。

session、JWT 与不透明令牌

三种方案解决的是同一个问题:请求之间怎么记住「你是谁」。session 把状态存在服务端,浏览器只拿一个 session id;JWT 把状态编码进令牌,服务端不存;不透明令牌是一个随机字符串,服务端查存储来还原身份。没有绝对更好的方案,只有和部署形态、吊销需求匹配的选择。

服务端 session

状态在服务端,改权限、强制下线都直接生效。多实例需要共享存储,否则请求打到另一台机器就丢了会话。适合有统一会话存储、需要即时吊销的后台系统。

JWT

服务端无状态,校验只靠签名和过期时间,横向扩展简单。代价是签发后很难撤销,令牌泄露只能等过期;权限变化也要等新令牌。适合短生命周期、调用方分散的 API。

不透明令牌

令牌本身不携带信息,服务端每次查 Redis 或数据库。可以随时删除、精确控制过期,代价是每个请求多一次存储查询。适合需要吊销、令牌数量不大的场景。

实际项目经常组合使用:短期 access token 用 JWT,减少校验开销;长期 refresh token 用不透明随机串,存在服务端,可吊销、可轮换。这样既保留无状态校验的速度,又给「退出登录」和「被盗令牌」留了处理入口。

JWT 的结构与校验边界

JWT 是三段用点分隔的字符串:头部、载荷、签名。头部声明算法和类型,载荷放 claims,签名是对前两段的签名。载荷只是 Base64URL 编码,不是加密,任何人都能解开看到内容;所以不要把密码、身份证号、内部密钥放进 JWT。签名保证的是「没被篡改」,不是「看不见」。

常用 claims 有:sub 表示主体,通常是用户 id;iss 表示签发方;aud 表示接收方;exp 过期时间;iat 签发时间;nbf 生效时间;jti 令牌唯一 id。校验时不要只看签名,还要校验签发方、接收方和过期时间,否则别的系统签发的令牌也可能被你的服务接受。

算法选择上,单体服务常用 HS256,对称密钥同时用于签发和校验;多服务、需要让第三方校验时用 RS256 或 ES256,公钥可以分发。无论哪种,校验函数都必须限制允许的算法。历史上有过把头部改成 none 或换成非对称算法来绕过校验的攻击,根因就是服务端信任了令牌自己声明的算法。

密钥要有足够长度,放在环境变量或密钥服务里,不能写进代码和仓库。演示代码允许一个默认值,但生产启动时必须检查:如果 JWT_SECRET 为空或仍是示例值,直接拒绝启动。密钥轮换时在头部加 kid,服务端按 kid 选择对应密钥,老令牌在过期前继续可用,新令牌用新密钥签发。

登录:bcrypt 与失败限流

密码不能明文存,也不能用普通哈希。bcrypt 是专门为密码设计的慢哈希,内置盐值,计算成本可调。Go 里用 golang.org/x/crypto/bcrypt,GenerateFromPassword 生成,CompareHashAndPassword 比较。成本因子每加一,计算时间大约翻倍;默认成本 10 在普通服务器上约几十毫秒,够用,调到 14 以上会让登录接口变成 CPU 瓶颈。

bcrypt 只处理前 72 个字节,超长密码会被截断。这不是让你限制用户密码长度,而是注册时要明确拒绝超长输入,避免「两个不同的长密码得到相同结果」。比较函数本身是恒定时间设计,不要自己用字符串相等去比哈希。

登录失败信息要统一。邮箱不存在和密码错误都返回同一句「账号或密码错误」,不要分别提示,否则攻击者可以枚举哪些邮箱注册过。对于不存在的用户,也可以拿一个固定的假哈希做一次比较,让响应时间接近,减少时序侧信道。这个细节不能完全消除差异,但比直接返回「用户不存在」好。

限流要按账号和来源一起做。只按 IP 限流,攻击者换代理就能绕过;只按账号限流,会让被攻击的用户自己登不上。常见组合是:同一账号连续失败若干次后锁定一段时间,同一 IP 每分钟限制尝试次数,成功登录后清零。计数放 Redis 或数据库,多实例才能共享;进程内计数在滚动发布时会归零,防护形同虚设。

hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
if err != nil {
	return err
}
if err := bcrypt.CompareHashAndPassword(hash, []byte(input)); err != nil {
	return ErrBadCredentials
}

签发、校验与 401 的分工

module demo/authdemo

go 1.27.3

require (
	github.com/gin-gonic/gin v1.10.1
	github.com/golang-jwt/jwt/v5 v5.2.1
	golang.org/x/crypto v0.31.0
)

登录成功后签发 access token,有效期通常十几分钟到一小时,越短越安全,但刷新越频繁。令牌里至少放用户 id 和角色,角色只作为展示或粗粒度判断,真正的权限仍要查服务端数据。签发时设置 iss、sub、exp、iat,需要跨服务时再加 aud。

type Claims struct {
	UserID string `json:"uid"`
	Role   string `json:"role"`
	jwt.RegisteredClaims
}

claims := Claims{
	UserID: uid,
	Role:   "user",
	RegisteredClaims: jwt.RegisteredClaims{
		Issuer:    "demo-auth",
		Subject:   uid,
		ExpiresAt: jwt.NewNumericDate(time.Now().Add(15 * time.Minute)),
		IssuedAt:  jwt.NewNumericDate(time.Now()),
	},
}
tok, err := jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString(secret)

校验中间件先解析 Authorization 头。格式是 Bearer 空格 令牌,缺头、格式不对、令牌为空都返回 401,并带上 WWW-Authenticate: Bearer。解析用 jwt.ParseWithClaims,同时传入允许的算法、签发方和「必须有过期时间」的选项;解析失败和 token.Valid 为 false 都按无效处理。

令牌校验的四个动作
取 Authorization
解析令牌
校验算法与过期
写入上下文
token, err := jwt.ParseWithClaims(tokenStr, claims,
	func(t *jwt.Token) (any, error) {
		if t.Method.Alg() != jwt.SigningMethodHS256.Alg() {
			return nil, errors.New("unexpected signing method")
		}
		return secret, nil
	},
	jwt.WithValidMethods([]string{"HS256"}),
	jwt.WithIssuer("demo-auth"),
	jwt.WithExpirationRequired(),
	jwt.WithLeeway(30*time.Second),
)

过期和无效要分开表达。中间件可以用 errors.Is(err, jwt.ErrTokenExpired) 判断过期,返回一个稳定的业务错误码,比如 token_expired;签名错误、格式错误返回 token_invalid。前端据此决定是「刷新一次」还是「直接退出登录」。状态码仍然是 401,区别放在响应体里,不要用 403 表示过期,403 的含义是「已认证但无权」。

本机实际跑了一遍登录与校验。登录接口返回的令牌很长,这里截断显示,字段和状态码是真实输出:

go mod tidy
go build -o authdemo.exe .
$env:APP_PORT="18089"
.\authdemo.exe

curl -i -X POST http://127.0.0.1:18089/v1/login \
  -H "Content-Type: application/json" \
  -d '{"email":"demo@example.com","password":"demo-pass"}'

curl -i http://127.0.0.1:18089/v1/me
curl -i http://127.0.0.1:18089/v1/me -H "Authorization: Bearer $TOKEN"
{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJ1XzQy...(已截断)","token_type":"Bearer","expires_in":900}

不带令牌访问受保护接口,实际返回:

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 32

{"error":"missing bearer token"}

带上令牌访问同一个接口,返回当前用户:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 28

{"role":"user","uid":"u_42"}

密码错误的登录返回 401 和统一的 {"error":"bad credentials"};用普通用户令牌访问管理员接口返回 403 和 {"error":"forbidden"}。这四组返回说明 401 和 403 的分工:前者是「你是谁不清楚」,后者是「知道你是谁,但不允许」。

把用户传下去:不要用字符串 key

校验通过后,中间件需要把用户信息传给处理函数。最直接的做法是 c.Set("user", user),但字符串 key 没有类型约束,任何包都能读写同一个名字,冲突时编译器不会提醒。更安全的做法是用一个未导出的自定义类型作为 context key,并只暴露存取函数。

type ctxKey struct{}

type AuthUser struct {
	UserID string
	Role   string
}

func WithUser(ctx context.Context, u AuthUser) context.Context {
	return context.WithValue(ctx, ctxKey{}, u)
}

func UserFromContext(ctx context.Context) (AuthUser, bool) {
	u, ok := ctx.Value(ctxKey{}).(AuthUser)
	return u, ok
}

中间件把用户写进 c.Request.Context(),处理函数通过 UserFromContext 取。未导出的 key 类型只有本包能构造,别的包无法用同名 key 覆盖,类型断言也只会匹配 AuthUser。处理函数必须检查第二个返回值:缺失时返回 500 或 401,不能直接断言后使用,否则路由配置错误会变成 panic。

不要把整个 *gin.Context 存进 context 或全局变量。它是请求级对象,请求结束后会被复用;异步任务里拿着它,可能读到下一个请求的数据。需要异步时用 c.Copy(),并且只复制需要的值,不要复制整个上下文。

有些团队把用户信息放在 Gin 的 c.Set 里,这也可以,但同样要提供类型安全的读取函数,并在 key 里加上包名前缀。无论用哪种方式,原则相同:key 要有命名空间,值要有明确类型,读取必须判空。字符串 key 加 any 的组合,是把类型错误推迟到运行时。

权限判断必须落在服务层

中间件适合做「认证」:令牌有效吗,用户是谁。它不适合做「授权」:这个用户能不能操作这一条数据。原因很实际:中间件通常只看路径和方法,看不到资源归属;而资源归属要查数据库才知道。把角色判断全放在中间件里,只能挡住「整组接口」,挡不住「同组里某一条数据」。

典型的越权路径是:接口 GET /v1/orders/:id 在登录组里,中间件确认了令牌有效,处理函数直接用 id 查询并返回。用户 A 把 id 改成用户 B 的订单号,只要这个 id 存在,就能看到别人的订单。这类漏洞叫 IDOR,根因不是令牌,而是缺少「资源属于当前用户」的判断。

正确顺序是:处理函数先从上下文拿当前用户,再按 id 查资源,查到后比较资源归属;不属于当前用户时返回 403 或 404。返回 404 更安全,避免攻击者通过状态码判断某个 id 是否存在。管理员绕过归属检查时,也要在服务层显式判断角色,不要依赖中间件曾经放行。

u, ok := auth.UserFromContext(c.Request.Context())
if !ok {
	c.JSON(http.StatusUnauthorized, gin.H{"error": "not authenticated"})
	return
}
order, err := svc.GetOrder(c.Request.Context(), id)
if errors.Is(err, store.ErrNotFound) {
	c.JSON(http.StatusNotFound, gin.H{"error": "order not found"})
	return
}
if order.UserID != u.UserID && u.Role != "admin" {
	c.JSON(http.StatusForbidden, gin.H{"error": "forbidden"})
	return
}

角色判断也一样。中间件可以拦「非管理员不能进 /admin 组」,但组内某个接口要求「超级管理员才能删除」,仍然要在服务层再判断一次。权限规则越靠近业务,越容易写对;越靠近路由,越容易漏掉。中间件是粗筛,服务层是最终判定。

多租户系统还要加租户维度。用户属于哪个租户、资源属于哪个租户,两个 id 都要校验;只校验角色不校验租户,管理员仍然能跨租户读数据。租户 id 不要从请求参数取,应该从令牌或会话里取,再和资源上的租户字段比较。

刷新、吊销与密钥轮换

短期 access token 的价值在于泄露后的窗口小,但用户不能每十五分钟重新输密码,所以需要 refresh token。refresh token 更适合用不透明随机串,存服务端,和用户、设备、过期时间关联;每次刷新时轮换,旧的立即作废。如果同一个 refresh token 被使用两次,说明可能被盗,应该吊销整个令牌族并要求重新登录。

前端遇到 401 时只刷新一次。多个请求同时收到 401,应该共享同一个刷新 Promise,而不是每个请求各发一次;刷新失败就清理本地状态并跳转登录,停止重试。无限 401 循环通常不是后端返回错,而是前端把「刷新接口的 401」也当成「需要刷新」。刷新接口要排除在拦截器的刷新逻辑之外。

JWT 的吊销是它的代价。令牌签发后,服务端不存状态,想让某个令牌立刻失效,只能引入黑名单或版本号:在用户表里存一个 token_version,签发时写进 claims,校验时比对;改密码或强制下线时把版本加一,所有旧令牌立即失效。这需要每次校验查一次存储,等于把无状态的一部分代价拿回来。另一种做法是把 access token 有效期压得很短,接受最多几分钟的延迟。

密钥轮换要留重叠期。直接换掉密钥,所有已签发令牌立刻失效,用户会被集体踢下线。正确做法是发布新密钥、在 kid 里区分、服务端同时接受新旧密钥,等老令牌自然过期后再移除旧密钥。轮换期间日志里要能看到用了哪个 kid,否则出问题无法判断是哪一代密钥。

现象、原因与第一步

现象真实原因第一步查什么
前端无限 401 循环刷新接口的 401 也触发刷新,或没有单次刷新锁看拦截器是否排除登录和刷新路径,是否共享刷新请求
令牌刚签发就报无效签发与校验用了不同密钥,或 Base64 处理不一致核对两边的 JWT_SECRET 与部署环境
所有令牌突然失效密钥被轮换但没有重叠期,或服务重启后密钥变了检查密钥来源是否持久,是否按 kid 选择
令牌过期却返回 403把认证失败和授权失败混用区分 401 与 403 的分支,检查错误码
处理函数 panic 取不到用户上下文 key 不一致,或中间件没有执行打印路由组和中间件注册顺序,检查读取函数
用户看到别人的数据只校验登录,没有校验资源归属在查询条件里带上当前用户 id,或查后比较归属
登录接口响应时间差异明显用户不存在时直接返回,没做假哈希比较统一失败路径和比较成本,检查是否存在账号枚举
退出登录后令牌仍可用只清了前端本地存储,服务端没有吊销机制确认 refresh 是否作废,access 有效期是否足够短
令牌出现在日志或 URL 里调试时把 query 参数或完整头打进日志搜索日志字段,改为只记录令牌指纹或用户 id

边界与代价

JWT 无状态,换来的是吊销困难。只要令牌还在有效期内,服务端就无法单方面否认它,除非引入黑名单或版本号,而那又会增加每次请求的查询。选择 JWT 之前先问:业务能不能接受「退出后令牌仍可用几分钟」,能不能接受「改密码后旧令牌不立即失效」。不能接受,就用服务端会话或不透明令牌。

令牌存放位置各有风险。放 localStorage 简单,但页面上的任何 XSS 都能读走;放 HttpOnly Cookie 能挡住脚本读取,但要处理 CSRF,并且跨域配置更复杂。没有一种存放方式能同时消除 XSS 和 CSRF,能做的是缩短令牌寿命、加 SameSite、做输出转义,并准备吊销手段。

bcrypt 的成本是真实的。登录接口在高并发下会吃满 CPU,成本因子越高越明显。不要为了「更安全」把成本调到很高,然后靠扩容硬扛;先用默认成本,配合限流和账号锁定,再根据实测调整。密码哈希是防离线爆破的,不是防在线请求的,在线防护靠限流和监控。

权限判断放在服务层,会增加一些重复代码,也需要每个入口都记得写。可以把它收进一个统一的授权函数,或者让数据访问层强制带当前用户条件,但不要指望中间件包办。安全设计的代价是显式,写得啰嗦一点,比漏掉一条越权路径便宜。

当天能自己验证的练习

  1. 用本文的示例启动服务,先用错误密码登录,观察状态码和响应体;再用正确密码登录,把返回的 token 复制到环境变量里。
  2. 分别请求不带令牌、带正确令牌、带被改动一个字符的令牌的受保护接口,记录三次的状态码和响应体,确认签名校验生效。
  3. 用普通用户令牌请求管理员接口,确认返回 403;再把处理函数里的角色判断删掉,观察是否变成 200,理解「中间件放行不等于有权」。
  4. 把上下文 key 换成字符串 "user",另写一个中间件写入同名 key,观察处理函数取到的值是否被覆盖。
  5. 把令牌有效期改成 1 分钟,等待过期后请求接口,确认返回 401 而不是 403;再在客户端记录一次「只刷新一次」的逻辑。

小结

三句话:session、JWT、不透明令牌各有代价,先按吊销需求选;校验令牌要限制算法、校验签发方和过期时间,401 与 403 不能混用;用户信息用自定义类型 key 传递并判空,权限判断放到服务层,按资源归属校验。

请求进来、身份确认、数据读写都走通之后,还有一类工作不该占用请求线程:发邮件、生成报表、清理过期数据。下一篇从「每个请求都开一个 goroutine,流量一高峰就 OOM」开始,讲后台任务、worker 池、定时任务和优雅停机;鉴权决定谁能触发任务,任务系统决定这些动作能不能可靠完成。