配置详解
Config 是 CyberGo JWT 的统一配置入口。本页聚焦签名算法之外的安全与行为配置字段;签名密钥与算法选择见 签名算法。
配置概览
DefaultConfig() 提供合理的默认值,只需设置密钥即可使用:
| 字段 | 默认值 | 说明 |
|---|---|---|
AccessTokenTTL | 15 分钟 | 访问令牌有效期 |
RefreshTokenTTL | 7 天 | 刷新令牌有效期 |
Issuer | "jwt-service" | 写入 iss 声明并校验 |
SigningMethod | HS256 | 签名算法 |
ClockSkew | 0 | 时钟偏移容忍 |
RequireExpiration | false | 是否强制要求 exp 声明 |
RejectRefreshAsAccess | false | 拒绝刷新令牌被用作访问令牌(v1.2.3 新增) |
RotateRefreshTokens | false | 刷新时自动吊销旧刷新令牌,实现一次性轮换(v1.2.3 新增) |
ExpectedAudience | ""(不校验) | 预期受众 |
normalizeConfig 自动填充规则
New() 在校验前调用 normalizeConfig,对零值字段填充默认值。以下表格列出每条规则:
| 零值条件 | 填充的默认值 | 触发条件 |
|---|---|---|
AccessTokenTTL == 0 | 15 分钟 | 总是 |
RefreshTokenTTL == 0 | 7 天 | 总是 |
Issuer == "" | "jwt-service" | 总是 |
SigningMethod == "" | HS256 | 总是 |
RateLimitRate == 0 | 100 | 仅 EnableRateLimit == true |
RateLimitWindow == 0 | 1 分钟 | 仅 EnableRateLimit == true |
Blacklist.MaxSize == 0 | 100000 | 仅内置存储(Store == nil) |
Blacklist.CleanupInterval == 0 | 5 分钟 | 仅内置存储 |
Blacklist.EnableAutoCleanup | 强制 true | 内置存储恒为开启;字段本身仅自定义 Store 生效 |
何时触发速率限制默认值
RateLimitRate 和 RateLimitWindow 的默认值仅在 EnableRateLimit 为 true 时填充。若 EnableRateLimit 为 false(默认),速率限制不启用,这两个字段被忽略。详见 速率限制。
自定义 BlacklistStore 跳过填充
当 Blacklist.Store 不为 nil(使用自定义存储后端)时,MaxSize 与 CleanupInterval 被忽略,存储管理由后端自行负责。EnableAutoCleanup 则只在自定义 Store 时生效;内置存储恒为开启(归一化阶段强制为 true,防止内存无限增长)。
签发者与受众校验
Issuer(签发者)
设置 Issuer 后,创建令牌时写入 iss 声明,验证时校验一致性:
cfg := jwt.DefaultConfig()
cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!"
cfg.Issuer = "my-app-v1" // 令牌将携带 iss: "my-app-v1"验证时,如果令牌的 iss 不等于配置值,返回 ErrTokenInvalidIssuer。
库只补零值
库只补零值:调用方显式赋值的 iss/exp/iat/jti 会原样使用,覆盖配置与 TTL。以上面为例,若 claims.RegisteredClaims.Issuer 已被赋值为 "other-app",签发时不会写入 cfg.Issuer。验证时会因 iss 不匹配返回 ErrTokenInvalidIssuer,形成自签自验失败。统一签发方时不要手工设置 Issuer 字段。
ExpectedAudience(预期受众)
设置 ExpectedAudience 后,验证时检查令牌的 aud 声明是否包含此值:
package main
import (
"fmt"
"github.com/cybergodev/jwt"
)
func main() {
cfg := jwt.DefaultConfig()
cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!"
cfg.ExpectedAudience = "billing-api"
processor, err := jwt.New(cfg)
if err != nil {
panic(err)
}
defer processor.Close()
// 受众匹配的令牌
claims := &jwt.Claims{
UserID: "user1",
RegisteredClaims: jwt.RegisteredClaims{
Audience: jwt.StringOrSlice{"billing-api"},
},
}
token, err := processor.Create(claims)
if err != nil {
panic(err)
}
_, err = processor.Parse(token)
fmt.Println("Valid:", err == nil)
// 输出:Valid: true
// 受众不匹配的令牌会被拒绝
wrongClaims := &jwt.Claims{
UserID: "user2",
RegisteredClaims: jwt.RegisteredClaims{
Audience: jwt.StringOrSlice{"admin-api"},
},
}
wrongToken, _ := processor.Create(wrongClaims)
_, err = processor.Parse(wrongToken)
fmt.Println("Wrong audience valid:", err == nil)
// 输出:Wrong audience valid: false
}多服务场景
在微服务架构中,为不同服务设置不同的 ExpectedAudience,使一个服务签发的令牌无法被另一个服务接受,实现服务间令牌隔离。
时钟偏移(ClockSkew)
ClockSkew 为 exp(过期)和 nbf(生效前)校验提供宽容窗口,容忍签发方与验证方之间的时钟漂移。偏移对称作用于两个时间声明:
exp方向:令牌在exp + ClockSkew之后才被视为过期——放宽过期校验nbf方向:令牌在nbf - ClockSkew之前就已被视为生效——放宽生效前校验
cfg := jwt.DefaultConfig()
cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!"
cfg.ClockSkew = 30 * time.Second // 容忍 30 秒时钟偏差建议
分布式系统中,服务器间时钟可能存在数秒偏差。建议设置 ClockSkew = 30s ~ 60s。零值(默认)表示严格校验,不施加任何宽容。
ClockSkew 对令牌有效性的影响
以下表格展示 ClockSkew = 30s 时,一个 exp = 12:00:00、nbf = 12:00:00 的令牌在各验证时间点的有效性:
| 验证时间 | 与 exp 的关系 | 与 nbf 的关系 | 结果 |
|---|---|---|---|
11:59:20 | 未到期 | nbf - 40s(超出偏移) | 无效:ErrTokenNotValidYet |
11:59:40 | 未到期 | nbf - 20s(偏移窗口内) | 有效 |
12:00:00 | 未到期 | nbf 时刻 | 有效 |
12:00:10 | exp + 10s(偏移窗口内) | 已生效 | 有效 |
12:00:40 | exp + 40s(超出偏移) | 已生效 | 无效:ErrTokenExpired |
偏移仅放宽、不收紧
ClockSkew 只会扩大令牌的接受窗口,不会缩小严格校验下的窗口。零值等价于 RFC 7519 的严格语义:令牌恰好从 nbf 生效,恰好到 exp 过期。
ClockSkew 不允许为负数,Config.Validate() 会返回 ErrInvalidConfig。
强制过期(RequireExpiration)
默认情况下(RequireExpiration = false),没有 exp 声明的令牌不会过期。这在 RFC 7519 中是合法的,但在安全敏感场景下可能是隐患。
设置 RequireExpiration = true 后,验证时拒绝缺少 exp 声明的令牌:
cfg := jwt.DefaultConfig()
cfg.SecretKey = "hmac-key-that-has-at-least-32-bytes!"
cfg.RequireExpiration = true // 拒绝没有 exp 的令牌安全加固
本库签发的令牌总是携带 exp:零值时由 TTL 派生。因此 RequireExpiration 主要影响来自其他签发方的令牌或缺少 exp 的旧令牌。生产环境建议启用。该开关只判断 exp 是否存在,不检查其值是否合理。
令牌 TTL 设计
访问令牌和刷新令牌的 TTL 应根据业务场景平衡安全与体验:
| 场景 | AccessTokenTTL | RefreshTokenTTL | 说明 |
|---|---|---|---|
| 高安全(金融、医疗) | 5 分钟 | 1 小时 | 短 TTL 限制暴露窗口 |
| Web 应用 | 15 分钟 | 7 天 | 默认值,平衡安全与体验 |
| 移动端 App | 30 分钟 | 30 天 | 较长 TTL 减少重新登录 |
| 内部服务 | 1 小时 | 24 小时 | 内网信任度较高 |
约束
Config.Validate() 要求 AccessTokenTTL < RefreshTokenTTL,且两者必须为正数。
TTL 只作用于未显式设置的 exp
库只补零值:调用方显式赋值的 iss/exp/iat/jti 会原样使用,覆盖配置与 TTL。若在 Claims 中显式设置 ExpiresAt(例如设为 1 年后),令牌有效期就是这个值,AccessTokenTTL 不再生效,上面的 TTL 设计同时失效。业务代码不要直接写 ExpiresAt。
配置校验矩阵
Config.Validate() 在 New() 中于 normalizeConfig 之后执行,返回三类错误:ErrInvalidConfig、ErrInvalidSecretKey、ErrInvalidSigningMethod。
直接调用 Validate() 与经 New() 校验不等价:New() 会先补零值默认,直接调用则不会。同一份配置可能 Validate() 返回 TTL must be positive 而 New() 构造成功。需要与 New() 一致时,从 DefaultConfig() 出发。
签名密钥校验(按算法)
| 算法族 | SigningKey 要求 | VerificationKey(可选) |
|---|---|---|
| HMAC(HS256/384/512) | SecretKey 字符串 ≥ 32 字节 + 非弱密钥 | 不适用(HMAC 对称) |
| RSA(RS/PS 256/384/512) | *rsa.PrivateKey ≥ 2048 位 | *rsa.PublicKey ≥ 2048 位 |
| ECDSA(ES256/384/512) | *ecdsa.PrivateKey,曲线匹配算法 | *ecdsa.PublicKey |
VerificationKey 的作用
设置 VerificationKey 后,验证令牌时使用公钥而非私钥——适用于只验不签的服务(如资源服务器)。省略时验证使用 SigningKey 中的私钥。详见 签名算法。
Config.Validate() 完整检查项
| 检查项 | 条件 | 返回错误 |
|---|---|---|
| 配置指针 | nil | ErrInvalidConfig |
| HMAC 密钥长度 | SecretKey < 32 字节 | ErrInvalidSecretKey |
| HMAC 密钥强度 | 弱密钥(低熵/低复杂度) | ErrInvalidSecretKey |
| RSA 签名密钥类型 | 非 *rsa.PrivateKey | ErrInvalidSecretKey |
| RSA 签名密钥强度 | < 2048 位 | ErrInvalidSecretKey |
| RSA 验证密钥类型 | 非 *rsa.PublicKey(设置时) | ErrInvalidSecretKey |
| RSA 验证密钥强度 | < 2048 位(设置时) | ErrInvalidSecretKey |
| ECDSA 签名密钥类型 | 非 *ecdsa.PrivateKey | ErrInvalidSecretKey |
| ECDSA 曲线匹配 | 曲线与算法不匹配(如 ES256 需 P-256) | ErrInvalidSecretKey |
| ECDSA 验证密钥类型 | 非 *ecdsa.PublicKey(设置时) | ErrInvalidSecretKey |
| 签名算法 | 不在 12 种内置算法中 | ErrInvalidSigningMethod |
| AccessTokenTTL | <= 0 | ErrInvalidConfig |
| RefreshTokenTTL | <= 0 | ErrInvalidConfig |
| TTL 关系 | AccessTokenTTL >= RefreshTokenTTL | ErrInvalidConfig |
| ClockSkew | < 0 | ErrInvalidConfig |
| 限流参数符号 | EnableRateLimit == true 且 RateLimitRate < 0 或 RateLimitWindow < 0 | ErrInvalidConfig |
| RateLimitRate 上界 | EnableRateLimit == true 且 RateLimitRate > 1000000 | ErrInvalidConfig |
| RateLimitWindow 上界 | EnableRateLimit == true 且 RateLimitWindow > 30 天 | ErrInvalidConfig |
| Blacklist MaxSize | <= 0(仅内置存储) | ErrInvalidConfig |
| Blacklist CleanupInterval | <= 0(仅内置存储) | ErrInvalidConfig |
校验顺序
Validate() 先校验签名密钥(返回 ErrInvalidSecretKey 或 ErrInvalidSigningMethod),再校验 TTL、ClockSkew、限流参数和 Blacklist 配置(返回 ErrInvalidConfig)。若密钥不合法,后续检查不会执行;修复第一个报错后重新测试即可。
限流上界的意义
EnableRateLimit == true 时,限流参数必须非负,且每窗口次数不超过 1000000、窗口不超过 30 天,否则 New() 直接返回 ErrInvalidConfig。这些边界用于快速暴露配置错误;AllowN 内部另有溢出保护。详见 速率限制。
输入校验与安全加固
CyberGo JWT 对 Claims 字段实施多层输入校验,防止注入攻击和异常数据。深度字段校验只在令牌创建时执行。验证路径只调用 Validate()(必填字段)并清洗标准声明字符串。
字段约束
| 校验项 | 限制 | 触发错误 |
|---|---|---|
| 字符串字段长度 | ≤ 256 字节(UTF-8 编码后,中文约 85 字) | ValidationError |
| 数组大小(permissions、scopes、audience) | ≤ 100 项 | ValidationError |
| Extra 字段数量 | ≤ 50 个 | ValidationError |
| Extra 值类型 | string、[]string | ValidationError(拒绝嵌套 map) |
长度按字节计算:Go 的 len(string) 返回字节数,一个汉字在 UTF-8 下占 3 字节。85 个汉字为 255 字节可通过,86 个汉字为 258 字节会被拒绝。
受校验的字符串字段包括 UserID、Username、Role、SessionID、ClientID 以及 RegisteredClaims 中的 Issuer、Subject、ID、TokenType。
注入模式检测
库内置 46 种危险模式检测,覆盖 XSS、SQL 注入、路径穿越等攻击向量:
- XSS:
<script>、javascript:、onerror=、<iframe>等 HTML/JS 注入标签 - SQL 注入:
drop table、union select等 - 路径穿越:
../、/etc/passwd、file:// - 控制字符:除 Tab(9)、换行(10)、回车(13)外的 ASCII < 32 字符
检测到危险模式时返回 ValidationError,Field 为字段名,Message 为 "suspicious pattern detected"。
处理校验错误
token, err := processor.Create(claims)
if err != nil {
var ve *jwt.ValidationError
if errors.As(err, &ve) {
fmt.Printf("字段: %s, 原因: %s\n", ve.Field, ve.Message)
// 字段:UserID, 原因:suspicious pattern detected
}
}ValidationError 同时实现了 Unwrap(),可以通过 errors.Is 和 errors.As 链式查找底层错误。在 Create 路径中,深度校验产生的 ValidationError 会被 ErrInvalidClaims 包装;验证路径中 Validate() 失败同样包装为 ErrInvalidClaims。
自定义 Claims 校验
实现 CustomClaims 接口的类型,其自定义字段不会被深度校验,实现者需在 Validate() 方法中自行处理。深度字段校验只在令牌创建时执行,验证路径只调用 Validate()(必填字段)并清洗标准声明字符串。因此创建时通过校验的令牌,解析时不会再被长度或注入规则拦截。详见 自定义 Claims。
下一步
- 签名算法 — 算法选择与密钥配置
- 自定义 Claims — CustomClaims 接口实现
- 令牌刷新与轮换 — 双层令牌 TTL 与轮换策略
- Config API — Config 完整字段参考