Liwendong.JwtAuthorize 1.5.1

Liwendong.JwtAuthorize

JWT 辅助文件。

JWT 令牌签发与校验授权辅助。

安装

dotnet add package Liwendong.JwtAuthorize

说明

• 本包属于 LiwendongPackages 组件集合。
• 具体目标框架与依赖请参阅本包 .csproj 文件。

配置项（AppSettings）

JwtAesEncryptKey 加密与轮换

JWT 的 payload 只是 Base64Url 编码、并非加密，任何人解码即可看到全部 claim。因此签发时默认会把 uid_ip_登录时间_随机数 加密后写入 jti claim；解密在服务端完成，外部无法还原。

• 不配置 JwtAesEncryptKey：不加密，jti 以明文写入 token（ payload 中的 uid/IP 可被解码读取，适用于无敏感信息的内部场景）。
• 配置单个密钥：jti 加密后写入。
• 配置多个密钥（逗号分隔，每个 32 位）：第一个（最新）用于加密签发，其余（历史）仅用于解密此前签发的 token。更换密钥时按 新密钥,旧密钥 配置，旧 token 在轮换期内仍可正常解析；待旧 token 全部自然过期后，再把旧密钥从配置中移除。

注意：配置在进程启动时读取并缓存，修改后需重启应用生效。加密/不加密两种模式签发的 token 互不兼容（切换模式后旧 token 将失效）。

对外开放 API（JwtAuthorizeConfig）

调用方（宿主项目）可直接使用 Liwendong.JwtAuthorize.JwtAuthorizeConfig 静态类：

配置读取

var signKey = JwtAuthorizeConfig.GetSecurityKey();       // JWT 签名密钥（SymmetricSecurityKey）
var aesKeys = JwtAuthorizeConfig.GetAesEncryptKeys();    // AES 密钥集合，未配置时返回空数组
var issuer  = JwtAuthorizeConfig.GetIssuer();            // 签发者
var audience = JwtAuthorizeConfig.GetAudience();         // 受众
var expire  = JwtAuthorizeConfig.GetJwtExpire();         // 有效期（秒）
var reflash = JwtAuthorizeConfig.ReflashTime();          // 刷新窗口（秒）
var validateIp = JwtAuthorizeConfig.IsValidateIP();      // 是否校验 IP
var validateIssuer = JwtAuthorizeConfig.IsValidateIssuer();
var validateAudience = JwtAuthorizeConfig.IsValidateAudience();
var tokenParmName = JwtAuthorizeConfig.GetJwtTokenParmName();
var tokenCookieName = JwtAuthorizeConfig.GetJwtTokenCookieName();
var loginUrl = JwtAuthorizeConfig.GetLoginUrl();

AES 加解密（CBC + PKCS7，随机 IV 拼在密文前一起 Base64 输出）

JwtTokenHelper 提供无需传入密钥的重载，直接使用系统配置的 JwtAesEncryptKey（与库内部签发/解析 token 的逻辑完全一致）；未配置 JwtAesEncryptKey 时调用会抛出 InvalidOperationException：

string cipher = JwtTokenHelper.AesEncrypt("明文内容");
string plain  = JwtTokenHelper.AesDecrypt(cipher);

如需使用自定义密钥（不依赖系统配置），可改用 JwtAuthorizeConfig 的通用版本：

string cipher = JwtAuthorizeConfig.AesEncrypt("明文内容", "32位密钥");
string plain  = JwtAuthorizeConfig.AesDecrypt(cipher, "32位密钥");

版本历史

1.5.1 (2026-10-21)

• 修复：jti 的 ip 段若含下划线（如伪造的 X-Real-IP 头、异常网卡名等），会破坏 {uid}_{ip}_{time}_{rand} 的右侧固定段数解析，导致 uid 被拼接进 ip 前缀、解析出被篡改的 uid。现写入前将 ip 段的 %/_ 转义为 %25/%5F、解析后还原，段内不再含分隔符；正常 IPv4/IPv6 地址不含这两个字符，新旧 token 完全兼容
• 说明：uid 含下划线始终安全（解析从右侧按固定段数切分，uid 为左侧剩余部分），本次仅补上 ip 段的转义

1.5.0 (2026-10-21)

• 新增：JwtTokenHelper.AesEncrypt/AesDecrypt 公开重载——密钥直接使用系统配置的 JwtAesEncryptKey（无需外部传入），加解密逻辑与库内部一致；未配置 JwtAesEncryptKey 时调用抛出 InvalidOperationException

1.4.0 (2026-10-21)

• 新增：JwtAesEncryptKey 改为选填——配置了才加密 jti，未配置则不加密（明文写入 token）；两种模式互不兼容
• 新增：配置读取方法与 AES 加解密方法提取至公开静态类 JwtAuthorizeConfig，调用方可直接获取配置信息并复用加解密能力

1.3.0 (2026-10-21)

• 修复：读取/解析 Token 时，AES 解密失败（如更换 JwtAesEncryptKey 后解析旧 token、密文被篡改或截断）会抛出未处理的 System.Security.Cryptography.CryptographicException: 填充无效，无法被移除，现按无效 token 处理（返回 null，引导重新登录），不再冒泡成未处理异常
• 新增：JwtAesEncryptKey 支持逗号分隔的多个密钥，实现平滑轮换（新密钥加密、历史密钥解密旧 token）