JWT on 姚玉亮的网络日志

基于 RSA 非对称签名签发 JWT 的多系统单点登录实践

Fri, 12 Apr 2024 10:30:00 +0800

HMAC 差在哪

我们在某科技公司做统一认证中心时，多个业务系统（统一支付平台、数据治理服务、知识库问答服务等）各自维护登录态，用户在系统间跳转要反复登录。最初考虑过用 HMAC 对称签名签发 JWT，但那样每个下游系统都得持有同一把密钥，一处泄露，整个认证体系就崩了，轮换密钥还得挨个通知所有业务方，运维成本很高。

最后选了 RSA 非对称签名：统一认证中心持私钥签发 JWT，各业务系统只持公钥验签，私钥永远不离开认证中心。

私钥签发，公钥验签

整体流程是：用户在统一认证中心登录后，认证中心用 RSA 私钥签发 Access Token 和 Refresh Token，写进 Cookie 或通过 Authorization 头返回。业务系统在网关层用公钥本地验签，不需要每次回调统一认证中心，认证中心的压力也小。

JWT 里放了 user_id、app_id、team_id、roles、exp、iss、aud 这些声明。iss 固定为 passport，aud 是目标应用的 AppID，防止 token 被跨应用滥用。Access Token 有效期 2 小时，Refresh Token 7 天，刷新时轮转新 Token。

代码里就两个函数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


import (
 "crypto/rsa"
 "time"

 "github.com/golang-jwt/jwt/v5"
)

type Claims struct {
 UserID int64 `json:"user_id"`
 AppID string `json:"app_id"`
 TeamID int64 `json:"team_id"`
 Roles []string `json:"roles"`
 JTI string `json:"jti"`
 jwt.RegisteredClaims
}

func (s *Service) SignToken(c *Claims, ttl time.Duration) (string, error) {
 c.RegisteredClaims = jwt.RegisteredClaims{
 Issuer: "passport",
 Audience: jwt.ClaimStrings{c.AppID},
 ExpiresAt: jwt.NewNumericDate(time.Now().Add(ttl)),
 IssuedAt: jwt.NewNumericDate(time.Now()),
 ID: c.JTI,
 }
 tok := jwt.NewWithClaims(jwt.SigningMethodRS256, c)
 return tok.SignedString(s.privKey) // *rsa.PrivateKey
}

func ParseToken(pub *rsa.PublicKey, tokenStr string) (*Claims, error) {
 claims := &Claims{}
 tok, err := jwt.ParseWithClaims(tokenStr, claims, func(t *jwt.Token) (interface{}, error) {
 if _, ok := t.Method.(*jwt.SigningMethodRSA); !ok {
 return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
 }
 return pub, nil
 })
 if err != nil || !tok.Valid {
 return nil, err
 }
 return claims, nil
}

验签逻辑放在各业务系统的 gRPC/HTTP 拦截器里，公钥通过配置中心下发。密钥轮转也支持：统一认证中心同时挂载新老两把私钥签发，公钥端点暴露 JWKS，业务系统定期拉取缓存。

alg=none 和另外两个坑

一是 alg=none 攻击。ParseWithClaims 的回调里必须校验 t.Method 是 RS256，不能信任 header 里的 alg。

二是 JWT 无法主动失效。我们用 Redis 维护黑名单，退出登录时把 jti 写进去，直到 token 自然过期才出黑名单。代价是每次请求多一次 Redis 查询，用 pipeline 加本地短缓存，压到可接受。

三是密钥轮转初期踩过坑：新私钥签发的 token，老业务系统还没拉到新公钥，验签直接失败。后来改成两把私钥灰度签发、JWKS 缓存 10 分钟、切换前先发公钥再切私钥，才算平稳。

后来

RSA 非对称签名让私钥收敛在认证中心，下游只持公钥，安全性和可扩展性都比 HMAC 好。配合短有效期 Access Token、Refresh Token 轮转和 Redis 黑名单，多业务系统的 SSO 就立住了。后续要接微信、企微、飞书登录，也只是多一种签发来源，验签侧一行不用改。

封面图：pixishared / Flickr · CC BY-SA 2.0

OAuth2/OIDC 认证中心实现：authorize/token/userinfo 与 JWKS

Wed, 27 Mar 2024 10:30:00 +0800

自定义协议走不通了

统一认证中心第一版只做了内部系统的 SSO，用的是自定义的 cookie + session 方案。后来要接入外部第三方应用，还要让企业客户拿自己的飞书/企微做身份源（IdP），自定义协议就走不通了。于是我决定把它改造成标准的 OAuth2/OIDC Provider：任何符合协议的客户端都能接入，认证中心自己也能作为 RP 去对接外部 IdP。

标准协议听起来就是实现几个端点的事，真落地才发现一堆工程细节等着：授权码模式的 PKCE、state/nonce 防 CSRF、redirect_uri 严格校验、ID Token 的签名与 claims、JWKS 公钥轮换。

四个端点

OIDC 在 OAuth2 之上加了身份层，核心要实现四个端点：

GET /oauth/authorize：用户登录与授权同意，返回 code；
POST /oauth/token：用 code 换 access_token / id_token / refresh_token；
GET /oauth/userinfo：用 access_token 取用户信息；
GET /.well-known/openid-configuration 和 /oauth/jwks：发现文档与公钥集合。

授权码模式（Authorization Code）+ PKCE 作为默认，所有 public client 强制 PKCE；client credentials 留给服务间调用。

/authorize：先校验，再谈登录

这个端点先做参数校验，再看登录态，没登录就跳登录页，state 带上保证回跳：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47


func (h *OAuthHandler) Authorize(c *gin.Context) {
 var req AuthorizeReq
 if err := c.ShouldBindQuery(&req); err != nil {
 c.String(400, "invalid request")
 return
 }
 app, err := h.appSvc.VerifyRedirectURI(c, req.ClientID, req.RedirectURI)
 if err != nil {
 c.String(400, "invalid redirect_uri")
 return
 }
 if req.ResponseType != "code" {
 c.Redirect(302, appendErr(req.RedirectURI, "unsupported_response_type", req.State))
 return
 }
 // PKCE: code_challenge 必填
 if req.CodeChallenge == "" || req.CodeChallengeMethod != "S256" {
 c.Redirect(302, appendErr(req.RedirectURI, "invalid_request", req.State))
 return
 }

 userID, loggedIn := session.GetUserID(c)
 if !loggedIn {
 c.Redirect(302, "/login?redirect="+url.QueryEscape(c.Request.RequestURI))
 return
 }

 code, err := h.authSvc.CreateAuthCode(c, AuthCode{
 AppID: app.AppID,
 UserID: userID,
 RedirectURI: req.RedirectURI,
 Scope: req.Scope,
 Nonce: req.Nonce,
 CodeChallenge: req.CodeChallenge,
 ExpiresAt: time.Now().Add(60 * time.Second),
 })
 if err != nil {
 c.String(500, "server error")
 return
 }
 u, _ := url.Parse(req.RedirectURI)
 q := u.Query()
 q.Set("code", code)
 q.Set("state", req.State)
 u.RawQuery = q.Encode()
 c.Redirect(302, u.String())
}

/token：验完 code 和 PKCE 才发 token

客户端拿到 code 之后来换 token，服务端要校验 code 和 PKCE verifier，都过了才签发：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


func (h *OAuthHandler) Token(c *gin.Context) {
 if err := c.Request.ParseForm(); err != nil {
 c.JSON(400, tokenErr("invalid_request"))
 return
 }
 grant := c.PostForm("grant_type")
 clientID, secret, ok := c.Request.BasicAuth()
 if !ok {
 c.JSON(401, tokenErr("invalid_client"))
 return
 }
 app, err := h.appSvc.Authenticate(c, clientID, secret)
 if err != nil {
 c.JSON(401, tokenErr("invalid_client"))
 return
 }

 switch grant {
 case "authorization_code":
 code := c.PostForm("code")
 verifier := c.PostForm("code_verifier")
 ac, err := h.authSvc.ConsumeAuthCode(c, code, app.AppID)
 if err != nil {
 c.JSON(400, tokenErr("invalid_grant"))
 return
 }
 if !pkce.Verify(ac.CodeChallenge, verifier) {
 c.JSON(400, tokenErr("invalid_grant"))
 return
 }
 pair, err := h.tokenSvc.Issue(OIDCTokenInput{
 UserID: ac.UserID,
 AppID: app.AppID,
 Nonce: ac.Nonce,
 Scope: ac.Scope,
 AuthTime: ac.CreatedAt,
 })
 if err != nil {
 c.JSON(500, tokenErr("server_error"))
 return
 }
 c.JSON(200, gin.H{
 "access_token": pair.AccessToken,
 "id_token": pair.IDToken,
 "refresh_token": pair.RefreshToken,
 "token_type": "Bearer",
 "expires_in": 7200,
 "scope": ac.Scope,
 })
 case "refresh_token":
 // 省略：验证 refresh token 并重新签发
 }
}

PKCE 校验本身没什么玄机，就是 SHA256 + Base64URL：

1
2
3
4
5


func Verify(challenge, verifier string) bool {
 sum := sha256.Sum256([]byte(verifier))
 computed := base64.RawURLEncoding.EncodeToString(sum[:])
 return subtle.ConstantTimeCompare([]byte(computed), []byte(challenge)) == 1
}

ID Token 与 JWKS

ID Token 是 OIDC 的核心，标准 claims 一个不能少：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


func (s *Service) buildIDToken(input OIDCTokenInput, user *User) (string, error) {
 now := time.Now()
 claims := IDTokenClaims{
 Issuer: s.issuer,
 Subject: strconv.FormatInt(user.ID, 10),
 Audience: jwt.ClaimStrings{input.AppID},
 ExpiresAt: jwt.NewNumericDate(now.Add(2 * time.Hour)),
 IssuedAt: jwt.NewNumericDate(now),
 AuthTime: jwt.NewNumericDate(input.AuthTime),
 Nonce: input.Nonce,
 Name: user.Nickname,
 Picture: user.Avatar,
 Email: user.Email,
 Phone: user.Phone,
 }
 return jwt.NewWithClaims(jwt.SigningMethodRS256, claims).SignedString(s.privKey)
}

JWKS 端点暴露公钥，支持轮换：

1
2
3
4


func (h *OAuthHandler) JWKS(c *gin.Context) {
 set := h.keySvc.PublicKeySet() // 返回当前 + 上一把公钥
 c.JSON(200, gin.H{"keys": set})
}

公钥的 JSON 表示要用 jwk 格式（kty/n/e/x5c 等字段）。我用 lestrrat-go/jwx/jwk 来做序列化，不手写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import "github.com/lestrrat-go/jwx/jwk"

func (s *KeyService) PublicKeySet() jwk.Set {
 set := jwk.NewSet()
 for _, k := range s.activeKeys() {
 key, _ := jwk.New(k.PublicKey)
 key.Set(jwk.KeyIDKey, k.Kid)
 key.Set(jwk.AlgorithmKey, "RS256")
 key.Set(jwk.KeyUsageKey, "sig")
 set.AddKey(key)
 }
 return set
}

那些必须较真的细节

redirect_uri 必须精确匹配。早期为了图方便支持了前缀匹配，被安全团队指出有开放重定向风险，后来改成配置里的完整 URL 白名单，查询参数不参与匹配。

ID Token 的 nonce 一定要原样回传。客户端靠它防重放，如果我们漏传，严格的 OIDC 客户端会直接拒绝登录。

code 一次性使用，加短过期。我设成 60 秒过期、用后即删，而且同一个 code 被二次使用时，立即吊销该 app 下该用户的所有活跃 token，这也是 OAuth2 安全 BCP 的推荐做法。

公钥轮换要平滑。JWT header 里带 kid，资源服务器按 kid 从 JWKS 缓存公钥；换密钥时，新私钥签发的 token 带新 kid，旧公钥在 JWKS 里保留 7 天，让存量 token 自然过期。

/userinfo 默认只返回 sub，其他 claims 要看 access token 的 scope 里有没有 profile/email/phone。不能一股脑把用户信息全吐出去。

还有一条经验：别自己造 JWT 轮子。我签发用 golang-jwt/jwt/v5，JWK 处理用 lestrrat-go/jwx，两个都是社区主流，省得自己手写 base64 和 JSON 序列化时漏掉边界条件。

后来

实现标准 OAuth2/OIDC，工作量大头在把协议里那些 MUST/SHOULD 逐条落到工程里：PKCE、state/nonce、精确 redirect_uri、code 一次性、JWKS 轮换。改造完成后，任何标准 OIDC 客户端（NextAuth、Spring Security、Keycloak adapter）都能直接接入，飞书/企微作为外部 IdP 也能走同一个 OIDC 联邦框架，扩展性比自定义协议好得多：对接这件事，不再需要一对一谈判。

封面图：Strooks-traveller1 / Flickr · CC BY-SA 2.0

Gin 中间件实战：JWT 认证与请求日志异步落盘 MongoDB

Thu, 23 Nov 2023 10:30:00 +0800

审计日志一条不能丢

宠物医疗 SaaS 的 B/S 版后端需要统一的认证和审计。所有 API 请求都要校验 JWT，把用户和医院上下文提取出来；同时合规要求所有请求日志落盘，请求方法、路径、参数、响应状态码、耗时、操作者，一样不能少，保留半年备查。

同步写日志会拖慢接口响应。日志结构嵌套深、量又大，放 MySQL 里查询和归档都别扭，我选了 MongoDB，通过 channel 异步写，不阻塞主请求。

把身份塞进 Context

JWT 中间件用 golang-jwt/jwt/v5，从 Authorization 头解析 token，校验签名和过期时间，再把用户 ID、医院 ID、角色注入 gin.Context，后面的 handler 直接取用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


type Claims struct {
 UserID int64 `json:"uid"`
 HospID int64 `json:"hid"`
 RoleCode string `json:"rol"`
 jwt.RegisteredClaims
}

func JWTAuth(signingKey []byte) gin.HandlerFunc {
 return func(c *gin.Context) {
 tokenStr := c.GetHeader("Authorization")
 if len(tokenStr) > 7 && tokenStr[:7] == "Bearer " {
 tokenStr = tokenStr[7:]
 }
 if tokenStr == "" {
 c.AbortWithStatusJSON(401, gin.H{"code": 401, "msg": "missing token"})
 return
 }

 claims := &Claims{}
 token, err := jwt.ParseWithClaims(tokenStr, claims, func(t *jwt.Token) (interface{}, error) {
 if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
 return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
 }
 return signingKey, nil
 })
 if err != nil || !token.Valid {
 c.AbortWithStatusJSON(401, gin.H{"code": 401, "msg": "invalid token"})
 return
 }

 c.Set("uid", claims.UserID)
 c.Set("hid", claims.HospID)
 c.Set("rol", claims.RoleCode)
 c.Next()
 }
}

校验的时候要连签名算法一起校验，代码里那个 HMAC 断言就是干这个的，防 alg 混淆攻击。

channel 满了就写文件

日志中间件用 ResponseWriter 包装器捕获响应状态码和响应体大小，通过一个带缓冲 channel 把日志投递给后台 writer。

这里有个和埋点上报不一样的前提。埋点丢几条无所谓，审计日志一条不能丢。所以同样是非阻塞投递，channel 满时的动作不同：不丢弃，降级写本地文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


type AccessLog struct {
 TraceID string `bson:"trace_id"`
 UserID int64 `bson:"user_id"`
 HospID int64 `bson:"hosp_id"`
 Method string `bson:"method"`
 Path string `bson:"path"`
 Query string `bson:"query"`
 ClientIP string `bson:"client_ip"`
 StatusCode int `bson:"status_code"`
 Latency time.Duration `bson:"latency"`
 ReqSize int `bson:"req_size"`
 RespSize int `bson:"resp_size"`
 ErrMsg string `bson:"err_msg,omitempty"`
 CreatedAt time.Time `bson:"created_at"`
}

type bodyWriter struct {
 gin.ResponseWriter
 size int
}

func (w *bodyWriter) Write(b []byte) (int, error) {
 n, err := w.ResponseWriter.Write(b)
 w.size += n
 return n, err
}

func AccessLogMiddleware(logCh chan<- *AccessLog, fallback *os.File) gin.HandlerFunc {
 return func(c *gin.Context) {
 start := time.Now()
 bw := &bodyWriter{ResponseWriter: c.Writer}
 c.Writer = bw

 c.Next()

 entry := &AccessLog{
 TraceID: c.GetString("trace_id"),
 Method: c.Request.Method,
 Path: c.Request.URL.Path,
 Query: c.Request.URL.RawQuery,
 ClientIP: c.ClientIP(),
 StatusCode: c.Writer.Status(),
 Latency: time.Since(start),
 ReqSize: int(c.Request.ContentLength),
 RespSize: bw.size,
 CreatedAt: start,
 }
 if uid, ok := c.Get("uid"); ok {
 entry.UserID = uid.(int64)
 }
 if hid, ok := c.Get("hid"); ok {
 entry.HospID = hid.(int64)
 }
 if len(c.Errors) > 0 {
 entry.ErrMsg = c.Errors.String()
 }

 select {
 case logCh <- entry:
 default:
 // channel 满，降级写本地文件，保证审计日志不丢
 json.NewEncoder(fallback).Encode(entry)
 }
 }
}

后台 writer 攒批写 MongoDB，用的是 BulkWrite：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32


func LogWriter(ctx context.Context, coll *mongo.Collection, ch <-chan *AccessLog) {
 batch := make([]mongo.WriteModel, 0, 200)
 ticker := time.NewTicker(500 * time.Millisecond)
 defer ticker.Stop()

 flush := func() {
 if len(batch) == 0 {
 return
 }
 _, err := coll.BulkWrite(ctx, batch)
 if err != nil {
 log.Printf("mongo bulk write error: %v", err)
 }
 batch = batch[:0]
 }

 for {
 select {
 case e := <-ch:
 m := mongo.NewInsertOneModel().SetDocument(e)
 batch = append(batch, m)
 if len(batch) >= 200 {
 flush()
 }
 case <-ticker.C:
 flush()
 case <-ctx.Done():
 flush()
 return
 }
 }
}

四个坑

第一个坑是请求体。最开始我直接把 c.Request.Body 读出来记日志，读完之后后续 handler 再读就是空的：body 是个流，读一次就没了。要用 io.NopCloser 加 bytes.Buffer 复制一份放回去。另外大 body 必须截断，只记前 1KB，不然日志体积很快失控。

第二个是敏感字段。密码、身份证、手机号不能明文进日志。我在序列化前对 query 和 body 里的 password、id_card、phone 做了掩码。这事必须在入口做，等数据入了库再补救就晚了，合规也不认。

第三个是 MongoDB 写入延迟。BulkWrite 攒到 200 条批量写，平时延迟很稳，但副本集发生主从切换时写入会短暂失败。flush 失败就把批次写回本地文件，一个补传任务定期扫描重放，保证审计数据最终不丢。

第四个是 JWT 的注销。JWT 无状态，token 在过期前没法主动作废。我们在 Redis 里维护黑名单：退出登录或改密码时把 jti 加进去，TTL 设成剩余有效期。代价是每个请求多一次 Redis 查询，我觉得值。

后来

这两个中间件后来成了我所有 Go Web 项目的基础组件。回头看，主流程都不难，难的全是边角：body 读完要放回，日志要异步但不能丢，token 要能注销，敏感字段要在入口脱敏。边角处理好了，才算能用。

封面图：Tawheed Manzoor / Flickr · CC BY 2.0