17370845950

必须调用 token.Valid 或 VerifySignature 才完成验签，仅 Parse 仅解析结构；自定义 Claims 需嵌入 jwt.RegisteredClaims 并导出字段；RS256 验证须用 ParsePKIXPublicKey 解析 PEM 公钥；ParseUnverified 仅限调试或动态选密钥，绝不可用于授权。

如何用 github.com/golang-jwt/jwt/v5 验证和解析 JWT

Go 官方不提供 JWT 实现，主流选择是 github.com/golang-jwt/jwt/v5（v4 已归档，v5 是当前维护分支）。它支持 HS256、RS256 等常用算法，且明确区分签名验证与结构解析两步——这点常被忽略，导致“看似解析成功，实则未验签”的安全漏洞。

关键点：必须调用 token.Valid 或显式调用 token.VerifySignature，仅调用 jwt.Parse 不代表 token 合法。

• Parse 只做语法解析和基础结构校验（如 header 是否含 alg、payload 是否为合法 JSON）
• 签名是否有效、过期时间（exp）、生效时间（nbf）、签发者（iss）等均由 Valid 方法触发校验
• 若使用自定义 Claims 类型，需确保字段名首字母大写（导出），否则 JSON 反序列化失败

package main

import (
    "fmt"
    "time"
    "github.com/golang-jwt/jwt/v5"
)

type MyClaims struct {
    UserID uint   `json:"user_id"`
    Role   string `json:"role"`
    jwt.RegisteredClaims
}

func parseAndVerify(tokenString, secret string) (*MyClaims, error) {
    token, err := jwt.ParseWithClaims(tokenString, &MyClaims{}, func(t *jwt.Token) (interface{}, error) {
        return []byte(secret), nil // HS256 时返回密钥字节
    })
    if err != nil {
        return nil, err
    }
    if !token.Valid {
        return nil, fmt.Errorf("token is invalid: %w", err)
    }
    claims, ok := token.Claims.(*MyClaims)
    if !ok {
        return nil, fmt.Errorf("failed to cast claims")
    }
    return claims, nil
}

为什么 ParseUnverified 很危险，但有时又不得不用

jwt.ParseUnverified 跳过签名验证，只解析 header 和 payload。它在调试、日志审计或需要提前读取 kid（密钥 ID）以动态选择公钥的场景下有用，但绝不能用于权限判定前的主流程。

常见误用：用 ParseUnverified 提取 user_id 就直接查库授权——攻击者可伪造任意 payload 并绕过签名检查。

• 仅当后续仍会用正确密钥/公钥调用 Parse 或 VerifySignature 时，才可先用 ParseUnverified
• 若需根据 header["kid"] 查找对应 RSA 公钥，应先用 ParseUnverified 获取 kid，再加载公钥，最后用该公钥调用完整 Parse
• 永远不要把 ParseUnverified 的结果当作可信数据参与业务逻辑

RS256 场景下如何正确加载 PEM 公钥

使用 RSA 签名（RS256）时，验证端需持有 PEM 格式的公钥。常见错误是直接传入文件路径或字符串，而未解析为 *rsa.PublicKey。

Parse 的 keyFunc 必须返回 interface{}，对 RS256 来说就是 *rsa.PublicKey；若返回 []byte 或字符串会 panic。

• 用 crypto/x509.ParsePKIXPublicKey 解析 PEM 中的 -----BEGIN PUBLIC KEY----- 块
• 若 PEM 是证书（-----BEGIN CERTIFICATE-----），需先用 x509.ParseCertificate 再取 cert.PublicKey
• 避免硬编码公钥，建议从环境变量或配置中心加载 PEM 字符串，再解析

import (
    "crypto/rsa"
    "crypto/x509"
    "encoding/pem"
)

func loadRSAPublicKey(pemBytes []byte) (*rsa.PublicKey, error) {
    block, _ := pem.Decode(pemBytes)
    if block == nil {
        return nil, fmt.Errorf("failed to decode PEM block")
    }
    pub, err := x509.ParsePKIXPublicKey(block.Bytes)
    if err != nil {
        return nil, err
    }
    if rsaPub, ok := pub.(*rsa.PublicKey); ok {
        return rsaPub, nil
    }
    return nil, fmt.Errorf("not an RSA public key")
}

JWT 过期后 exp 字段为何有时不生效

即使 token payload 中有 "exp": 1717027200，token.Valid 仍可能返回 true——原因通常是未启用标准声明校验，或系统时间偏差过大。

• jwt.Parse 默认启用 VerifyExp、VerifyNbf、VerifyIat，但若自定义 Claims 未嵌入 jwt.RegisteredClaims，这些校验不会自动触发
• 务必确认你的 Claims 结构体嵌入了 jwt.RegisteredClaims（如上文 MyClaims 示例）
• 服务器系统时间误差超过 Leeway（默认 0 秒）会导致校验失败；可通过 WithExpirationRequired 等选项显式控制，但更推荐同步 NTP 时间
• 注意：exp 是 Unix 时间戳（秒级），不是毫秒；前端 JS 生成时若用 Date.now() 需除以 1000 并取整

最易被忽略的一点：开发时本地时间快 5 分钟，token 表面没过期，但部署到 UTC 服务器后立即失效。别只信日志里的 exp 值，用 time.Unix(claims.ExpiresAt, 0) 打印实际时间对比。