Kong项目中JWT签名验证的Base64URL编码问题解析

背景介绍

在Kong API网关从2.8.x版本升级到3.7.1版本的过程中，部分用户报告了JWT(JSON Web Token)签名验证失败的问题。这些用户在使用HS256算法生成JWT令牌时，虽然代码在旧版本Kong上运行良好，但在新版本中却出现了"invalid signature"的错误提示。

问题本质

经过深入分析，发现问题根源在于JWT规范中对Base64URL编码的严格要求。JWT标准明确规定，令牌的各部分必须使用Base64URL编码，而非普通的Base64编码。Base64URL是Base64的一种变体，主要做了以下修改：

1. 将加号(+)替换为减号(-)
2. 将斜杠(/)替换为下划线(_)
3. 省略末尾的等号(=)

在Kong 2.8.x版本中，JWT插件对编码格式的验证较为宽松，能够接受标准的Base64编码。但在3.7.1版本中，Kong严格遵循了RFC 7519规范，只接受正确的Base64URL编码格式。

技术细节

以Salesforce Apex代码为例，原始代码使用标准Base64编码：

String signature = EncodingUtil.base64Encode(blob.valueOf(HEAD)) + '.' + EncodingUtil.base64Encode(blob.valueOf(payload));

修正后的代码则应用了Base64URL编码规则：

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

这种差异导致了新旧版本Kong对同一令牌的不同处理结果。

影响范围

这一问题主要影响以下类型的客户端：

1. 使用非标准JWT库生成令牌的应用程序
2. 自行实现JWT生成逻辑而非使用成熟库的代码
3. 在URL参数中传递JWT的场景（标准Base64编码包含的+/字符在URL中需要转义）

解决方案

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

1. 使用标准的JWT库而非自行实现签名逻辑
2. 如果必须自行实现，确保严格遵循Base64URL编码规则
3. 检查并更新现有的JWT生成代码，添加必要的字符替换逻辑

最佳实践

为避免类似问题，建议开发人员：

1. 始终使用经过验证的JWT库（如java-jwt、jose等）
2. 在升级Kong版本前，充分测试JWT相关功能
3. 了解JWT规范中的编码要求，特别是Base64URL的特殊处理
4. 在代码审查时特别注意JWT生成部分的编码逻辑

总结

Kong 3.7.1版本对JWT验证的严格化实际上是对规范的更好遵循，虽然短期内可能造成一些兼容性问题，但从长远看提高了安全性和标准符合性。开发人员应当理解这一变化的技术背景，及时调整相关代码，确保系统的稳定运行。