Kong项目中JWT签名验证的Base64Url编码规范变更解析

背景介绍

在Kong网关从2.8.x版本升级到3.7.1版本的过程中，部分用户报告了JWT(JSON Web Token)客户端认证出现签名无效的问题。这些用户在使用HS256算法生成JWT时，原本在旧版本中能够正常工作的代码在新版本中突然失效。本文将深入分析这一变更的技术背景、原因及解决方案。

问题本质

核心问题在于Kong 3.7.1版本对JWT的Base64编码处理更加严格，要求必须符合RFC 7519规范中的Base64Url编码标准，而旧版本对此要求较为宽松。

技术细节解析

JWT结构要求

根据JWT规范，一个标准的JWT由三部分组成，用点号(.)分隔：

1. 头部(Header) - Base64Url编码
2. 载荷(Payload) - Base64Url编码
3. 签名(Signature) - Base64Url编码

Base64与Base64Url的区别

标准Base64编码使用以下字符集：

• 字母A-Z、a-z、数字0-9
• 特殊字符+和/
• 填充字符=

而Base64Url编码为了URL安全性做了以下调整：

• 将+替换为-
• 将/替换为_
• 省略末尾的=填充

实际案例对比

问题用户的原始代码直接使用标准Base64编码：

EncodingUtil.base64Encode(blob.valueOf(HEAD)) + '.' + EncodingUtil.base64Encode(blob.valueOf(payload))

修正后的代码符合Base64Url标准：

EncodingUtil.base64Encode(Blob.valueOf(JSON.serialize(header)))
    .replace('+', '-').replace('/', '_').substringBefore('=')

版本变更影响

Kong 3.7.1版本通过PR #11569严格实施了RFC 7519规范，这属于规范遵从性的改进，但确实带来了向后兼容性的影响。旧版本可能出于兼容性考虑，对非标准编码的JWT也予以接受。

解决方案建议

对于遇到此问题的用户，建议采取以下措施：

1. 客户端修正：确保JWT生成时使用正确的Base64Url编码
2. 服务端检查：验证Kong配置是否正确处理JWT
3. 文档说明：在升级文档中明确标注此变更点

最佳实践

为避免类似问题，开发时应注意：

• 始终使用符合RFC标准的JWT库
• 避免手动拼接JWT组件
• 在升级前充分测试认证流程
• 关注项目变更日志中的重大变更

总结

Kong项目对JWT处理的这一变更体现了开源项目向标准规范靠拢的趋势。虽然短期内可能造成部分用户的适配工作，但从长远看提高了系统的规范性和安全性。理解这一变更的技术背景，有助于开发者更好地构建和维护基于Kong的认证体系。