iTop 内置 firebase/php-jwt 版本演进全解读:从 2.0 到 7.0 的 JWT 安全加固与功能变迁
iTop 内置 firebase/php-jwt 版本演进全解读:从 2.0 到 7.0 的 JWT 安全加固与功能变迁
导读
本篇文章以 iTop 仓库内 lib/firebase/php-jwt/CHANGELOG.md 为核心骨架,系统梳理 PHP-JWT(firebase/php-jwt)从 2.0.0 到 7.0.5 的完整版本演进史,并结合 lib/firebase/php-jwt/src 下的真实源码,逐条解析各版本特性、破坏性变更与安全修复背后的底层实现。读完本文,你将掌握该库的算法支持矩阵、Key/JWK/CachedKeySet 三大核心抽象、密钥长度校验规则、异常体系设计,以及在 iTop 这类 PHP 8 项目中使用 JWT 时应当注意的升级与安全实践。
一、该库在 iTop 中的定位与安装方式
在深入版本历史之前,先明确这份 CHANGELOG 描述的对象在仓库中的位置。firebase/php-jwt 是一个符合 RFC 7519 的轻量级 PHP JWT 编解码库("A simple library to encode and decode JSON Web Tokens (JWT) in PHP"),其源码目录位于:
- lib/firebase/php-jwt/src/JWT.php —— 核心类,负责 JWT 的 encode / decode / sign / verify
- lib/firebase/php-jwt/src/JWK.php —— JSON Web Key 解析(JWKS → Key 对象)
- lib/firebase/php-jwt/src/Key.php —— 密钥与算法绑定的强类型对象
- lib/firebase/php-jwt/src/CachedKeySet.php —— 远程 JWKS 的缓存拉取与限流
- lib/firebase/php-jwt/src/ExpiredException.php、BeforeValidException.php、SignatureInvalidException.php、JWTExceptionWithPayloadInterface.php —— 异常体系
- lib/firebase/php-jwt/composer.json —— 包元数据(要求 PHP ^8.0,BSD-3-Clause 许可)
该库并非 iTop 自研,而是通过 Composer 引入的第三方依赖,这可以从根目录的 lib/composer/installed.json(composer 安装清单)得到确认。其下游消费者之一是 Azure OAuth2 客户端 lib/thenetworg/oauth2-azure/composer.json,即 iTop 在接入 Azure AD 登录等场景时会经由该库来签发/校验 JWT 令牌。因此,理解 php-jwt 的版本行为,本质上就是理解 iTop 认证链路中令牌安全边界的行为。
官方推荐通过 Composer 安装:
composer require firebase/php-jwt
如果 PHP 环境缺少 libsodium 扩展,为支持 EdDSA(Ed25519)签名还可可选安装:
composer require paragonie/sodium_compat
二、版本演进总览
CHANGELOG 记录的时间跨度从 2015 年 4 月的 2.0.0 一直延伸到 2026 年 3 月的 7.0.5,跨度超过十年。整体来看,演进可划分为三个时代:
| 时代 | 版本区间 | 主题 |
|---|---|---|
| 2.x 时代 | 2.0.0 – 2.2.0 | 引入算法白名单、leeway、自定义 header,奠定安全基础 |
| 3.x – 5.x 时代 | 3.0.0 – 5.0.0 | 引入命名空间、增加 RSA/ECDSA 算法与错误处理 |
| 6.x 时代 | 6.0.0 – 6.11.1 | 引入 Key 对象、JWK、CachedKeySet、ES/EdDSA 全曲线 |
| 7.x 时代 | 7.0.0 – 7.0.5 | 安全加固密集期:密钥长度校验、敏感参数标记、时间校验 |
| PHP 版本要求 | 3.0.0 起 >= 5.3 | 6.1.0 淘汰 5.x/7.0,7.x 要求 ^8.0 |
三、7.x 时代:以安全加固为核心的密集迭代
7.0.0 是 CHANGELOG 中标注了 ⚠️ Security Fixes 的重大版本,后续 7.0.2、7.0.4、7.0.5 均围绕安全与正确性持续打补丁。
3.1 7.0.0:密钥长度校验(可能破坏现有配置)
7.0.0 引入的关键安全修复是"add key size validation"(对应 JWT.php 中的校验逻辑),CHANGELOG 明确给出兼容性警告:
NOTE: This fix will cause keys with a size below the minimally allowed size to break.
也就是说,凡密钥长度低于最低允许值的现有系统,在升级后签名/验签会直接失败。具体校验规则在源码中清晰可见:
- RSA 密钥:
RSA_KEY_MIN_LENGTH = 2048,validateRsaKeyLength()通过openssl_pkey_get_details($key)读取bits,若小于 2048 抛DomainException('Provided key is too short')(JWT.php 中的validateRsaKeyLength方法)。 - EC 密钥:7.0.2 补充了 EC 密钥长度校验,
validateEcKeyLength()从算法名中提取最小位数(如 ES256 → 256、ES384 → 384),低于阈值同样抛DomainException。 - HMAC 密钥:
validateHmacKeyLength()要求密钥长度(字节 × 8)不小于哈希算法位数,例如 HS256 要求 ≥ 256 位,否则抛DomainException('Provided key is too short')。
这意味着 7.x 之后,"短密钥 + 高强度算法"这类不安全的组合会被库直接拒绝,从源头杜绝了弱密钥风险。升级到 7.0.x 前,请务必检查现有 RSA 密钥是否 ≥ 2048 位、HMAC 密钥是否满足对应哈希长度。
3.2 7.0.0:SensitiveParameter 属性与 ExpiredException 时间戳
7.0.0 还包含两项重要特性:
-
为安全关键参数添加
#[\SensitiveParameter]属性:在 JWT.php 中,decode()的$keyOrKeyArray、encode()的$key、sign()的$key、verify()的$keyMaterial以及 Key.php 构造函数的$keyMaterial均被标记为#[\SensitiveParameter]。该属性会在异常回溯中屏蔽敏感值,防止密钥材料在栈追踪中泄露到日志。 -
在
ExpiredException中存储时间戳:源码 ExpiredException.php 新增setTimestamp(int)/getTimestamp(): ?int。当JWT::decode检测到exp已过期时,会执行$ex->setTimestamp($timestamp)后再抛出,调用方据此可精确得知令牌失效的判定时间点。
3.3 7.0.0:校验 iat 与 nbf
7.0.0 的 Bug Fixes 中还包含 "validate iat and nbf on payload"。在 JWT.php 的 decode() 流程里可以看到:iat、nbf、exp 若存在且非数值,会直接抛 UnexpectedValueException('Payload xxx must be a number');随后依次执行:
nbf校验:floor($payload->nbf) > ($timestamp + static::$leeway)时抛BeforeValidException("Cannot handle token with nbf prior to ...");iat校验:仅在 未设置 nbf 时才检查(!isset($payload->nbf) && isset($payload->iat)),这是 6.6.0 引入的"only check iat if nbf is not used"语义的延续;exp校验:($timestamp - static::$leeway) >= $payload->exp时抛ExpiredException。
三者共同构成完整的时间有效性防线,且 iat/nbf 均向下取整(floor),这与 6.8.1 的"accept float claims but round down"行为一脉相承。
3.4 7.0.4 与 7.0.5:正确性收尾
- 7.0.4 做了两件事:一是为 README 中的所有示例补齐测试(保证文档示例可运行);二是 "use urlsafeB64Decode everywhere"——统一所有 Base64URL 解码路径为 JWT.php 中
urlsafeB64Decode()这一个入口,消除了内部解码方式不一致带来的边界问题。 - 7.0.5 修复了 "RSA from JWK sometimes returns empty Instance":当 JWK 中 RSA 公钥的 n/e 参数被解析成空实例时(可参考 JWK.php 中
createPemFromModulusAndExponent()的 PEM 构造逻辑)给出正确结果。
四、6.x 时代:JWK、CachedKeySet 与算法矩阵大扩充
6.x 是功能增长最快的时期,许多今天仍在使用的核心抽象都诞生于此时。
4.1 6.0.0:破坏性变更与 Key 对象
6.0.0 是一次向后不兼容的大版本(CHANGELOG 提示参见 Release Notes),核心变化包括:
- 引入
Key对象,用于消除"密钥/算法类型混淆"(key/algorithm type confusion)攻击面。从 Key.php 可见,Key同时持有$keyMaterial与$algorithm,JWT::decode在验签前会通过constantTimeEquals($key->getAlgorithm(), $header->alg)强制比对 JWT header 中的alg与 Key 声明的算法,不匹配即抛UnexpectedValueException('Incorrect key for this algorithm')(JWT.php 的decode()流程)。这就是杜绝"算法混淆攻击"(如把 RS256 令牌换成 HS256 用公钥当 HMAC 密钥)的关键机制。 - 同一版本新增 JWK 支持(
JWT::parseKey由 6.2.0 补充$defaultAlg参数)、ES256/ES384/Ed25519 支持。
4.2 6.2.0:CachedKeySet 与默认算法参数
6.2.0 引入 CachedKeySet(CachedKeySet.php),用于从公开 URI 拉取并缓存 JWKS,其设计目标可归纳为:
- 结果缓存,提升性能;
- 遇到未知
kid时自动刷新缓存,兼容密钥轮换; - 开启限流时,JWKS URI 每秒不超过 10 次请求。
源码实现上,CachedKeySet 实现 ArrayAccess,JWT::decode 的 getKey() 会直接通过 $keyOrKeyArray[$kid] 取值,触发 keyIdExists() 的"查缓存 → 未命中则 GET JWKS → 写回缓存"流程;rateLimitExceeded() 通过缓存项中的 callsPerMinute 计数,超过 maxCallsPerMinute = 10 即拒绝拉取,避免对提供方造成压力。6.3.0 进一步把 JWKS 以字符串形式缓存以规避序列化错误,6.10.1 则修复了限流过期时间"每次都要重新设置"的缺陷,确保限流计数窗口始终正确。
JWT::parseKeySet(array $jwks, ?string $defaultAlg = null) 则允许在 JWKS 中缺少 alg 字段时(RFC 7517 中该字段对 kty 可选)用默认算法兜底。
4.3 算法与曲线矩阵的持续扩充
CHANGELOG 中 6.x 的算法相关条目可汇总为下表:
| 版本 | 新增能力 | 源码佐证 |
|---|---|---|
| 6.3.0 | JWK 解析支持 ES256 | JWK.php EC_CURVES 常量 |
| 6.4.0 | 支持 W3C ES256K(secp256k1 曲线);JWKS 仅在必要时解码以优化缓存 | EC_CURVES['secp256k1'] = '1.3.132.0.10' |
| 6.7.0 | Ed25519 公钥的 JWK 支持(OKP 类型) | OKP_SUBTYPES['Ed25519'] |
| 6.8.0 | P-384 曲线支持 | EC_CURVES['P-384'] = '1.3.132.0.34' |
| 6.11.0 | oct 类型(对称密钥)JWK 支持 |
JWK.php 的 case 'oct' 分支 |
对照 JWT.php 中的 $supported_algs,7.x 最终支持的算法集合为:HS256/HS384/HS512(hash_hmac)、RS256/RS384/RS512(openssl)、ES256/ES256K/ES384(openssl)、EdDSA(libsodium)。ES 系列的签名在验签时需由原始 r||s 格式转换为 ASN.1 DER 序列(signatureToDER()),签发时反向转换(signatureFromDER()),这是 OpenSSL 与 JOSE 规范之间的格式差异所致。
4.4 解码体验与兼容性修补
6.x 还持续打磨解码接口与 PHP 版本兼容:
- 6.6.0:"allow get headers when decoding token"——
JWT::decode($jwt, $key, $headers)的第三个stdClass引用参数会回填 header(对应 JWT.php 的?stdClass &$headers = null)。注意 README 强调:不应在未验证签名前解码 header,未验证的 header 内容应视作攻击者可注入的任意字符串。 - 6.9.0:把导致异常的 payload 附加到异常对象中(
JWTExceptionWithPayloadInterface,见 JWTExceptionWithPayloadInterface.php),便于排查"哪个 claim 导致失败"。 - 6.10.0:允许覆盖
typheader(encode()的$head参数会与默认['typ' => 'JWT']合并)。 - 6.5.0:允许
kid为字符串'0'(此前会被误判为空),并淘汰 PHP 7.3。 - 6.10.2 / 6.3.1:分别支持 PHP 8.4(消除弃用警告)与 PHP 8.2 字符串插值语法。
五、6.0.0 之前的演进:安全基石的奠定
5.1 2.x:算法白名单与 leeway
- 2.0.0 是安全转折点:CHANGELOG 明确指出,"当对称与非对称密钥混用时,旧版本存在已知安全漏洞,强烈建议升级到 2.0.0+"。2.0.0 将
JWT::decode()的签名改为要求传入受支持算法数组,即强制调用方声明允许的算法集合,这正是今天Key对象强制alg匹配的前身。 - 2.1.0 引入
JWT::$leeway(默认 0),用于抵消签发方与验证方之间的时钟偏差,README 建议 leeway 不宜超过几分钟;同时$keys参数支持ArrayAccess对象。 - 2.2.0 允许向
JWT::encode()追加自定义可选 header。
5.2 3.x – 4.x:命名空间与可测试性
- 3.0.0:最低 PHP 版本提升到 5.3,引入
\Firebase\JWT命名空间,并要求非空密钥才能解码验签(防止"空密钥"绕过)。 - 4.0.0:改用静态
$timestamp替代直接调用time(),便于单元测试固定时间点(该设计在 JWT.php 中保留至今:$timestamp = is_null(static::$timestamp) ? time() : static::$timestamp);同时支持后期静态绑定(late static binding)。
5.3 5.x:RSA 算法扩充与错误处理
5.0.0 是一次功能里程碑:
- 支持 RS384 / RS512;
- 增加 RS256 的 openssl 示例;
- 检测签名中的非法 Base64 编码;
JWT::verify现在能处理 OpenSSL 错误(对应源码中openssl_verify返回-1时抛DomainException('OpenSSL error: ...'));decode方法增加array类型提示,并覆盖所有 JSON 错误类型(handleJsonError()中的 JSON_ERROR_DEPTH/STATE_MISMATCH/CTRL_CHAR/SYNTAX/UTF8 映射)。
六、源码级对照:decode 校验链与异常体系
把版本史落到当前代码上,JWT::decode() 的完整校验顺序(JWT.php 的 decode 方法)可以概括为一条清晰的"校验链":
- 空 Key / 空 Key 数组 →
InvalidArgumentException('Key may not be empty'); - 非三段式(
explode('.', $jwt)不等于 3)→UnexpectedValueException('Wrong number of segments'); - header / payload 的 Base64URL 解码与 JSON 解析失败 →
UnexpectedValueException; - payload 必须为 JSON 对象;
iat/nbf/exp非数值 →UnexpectedValueException; - 空
alg或不在$supported_algs→UnexpectedValueException; - 按
kid查找 Key(getKey(),支持Key、数组、ArrayAccess/CachedKeySet)→ 找不到抛UnexpectedValueException; - Key 算法与 header
alg不一致 →UnexpectedValueException('Incorrect key for this algorithm'); - ES 系列签名转 DER 后验签,失败 →
SignatureInvalidException; nbf/iat/exp时间校验 →BeforeValidException/ExpiredException。
对应的异常体系如下(全部位于 Firebase\JWT 命名空间,均继承 \UnexpectedValueException):
use Firebase\JWT\JWT;
use Firebase\JWT\SignatureInvalidException;
use Firebase\JWT\BeforeValidException;
use Firebase\JWT\ExpiredException;
use DomainException;
use InvalidArgumentException;
use UnexpectedValueException;
try {
$decoded = JWT::decode($jwt, $keys);
} catch (InvalidArgumentException $e) {
// 传入的 key/key 数组为空或格式错误
} catch (DomainException $e) {
// 算法不受支持、key 无效、OpenSSL/libsodium 出错、缺少 libsodium
} catch (SignatureInvalidException $e) {
// 签名验证失败
} catch (BeforeValidException $e) {
// 令牌在 nbf / iat 之前被使用
} catch (ExpiredException $e) {
// 令牌已过期(exp)
} catch (UnexpectedValueException $e) {
// 令牌格式错误、缺少/不支持 alg、alg 与 key 不匹配、kid 无效
}
其中 ExpiredException(ExpiredException.php)额外实现了 JWTExceptionWithPayloadInterface,可调用 getPayload() / getTimestamp() 获取引发异常的令牌载荷与判定时间戳,这是 7.0.0 与 6.9.0 两版特性叠加的成果。
七、对使用者的升级与实践建议
基于 CHANGELOG 与源码,给 iTop 及其扩展的 JWT 使用场景总结几点可落地的建议:
- 关注 7.0.0 的破坏性:升级后短于 2048 位的 RSA 密钥、短于哈希位数的 HMAC 密钥会被直接拒绝(
Provided key is too short)。升级前务必盘点现有密钥长度。 - 始终坚持算法白名单:无论用
Key对象还是$supported_algs数组,都要显式声明允许的算法,不要接受 header 中的任意alg,这是 2.0.0 至今反复加固的安全底线。 - 善用 leeway 但不滥用:
JWT::$leeway用于抵消时钟偏差,README 建议不超过几分钟;时间校验规则为exp用>=(含 leeway 收缩),nbf/iat用>(含 leeway 放宽),且iat仅在无nbf时才校验。 - 远程 JWKS 使用
CachedKeySet:它同时解决性能、密钥轮换(未知 kid 自动刷新)与限流(默认 10 次/分钟)三个问题;构造参数$expiresAfter与$rateLimit可分别控制缓存时长与限流开关。 - 不要把未验证的 header 当可信数据:如需 header 内容,先完成
decode验签,或明确意识到手工json_decode(base64_decode(...))解析出的 header 可能已被篡改。 - decode 返回值为 stdClass:如需关联数组,用
(array) $decoded或json_decode(json_encode($decoded), true)转换,这是 6.0.0 之后的固定返回类型。
结语
透过 lib/firebase/php-jwt/CHANGELOG.md 这份清单,可以看到一个被广泛使用的 JWT 库十年间的进化轨迹:2.x 确立算法白名单与 leeway,3.x/5.x 建立命名空间、算法矩阵与错误处理,6.x 打造 Key 对象、JWK 与 CachedKeySet 三大现代抽象,7.x 则以密钥长度校验、SensitiveParameter、时间 claim 校验等安全修复完成最后的闭环。这些演进既体现在 lib/firebase/php-jwt/src 的每一行源码中,也直接决定了 iTop 认证与 OAuth2 集成场景下令牌校验的安全边界。升级或使用该库时,以 CHANGELOG 为线索、以源码为印证,是最稳妥的实践路径。