Docker Registry 3.0 版本中 JWT 令牌验证机制的变化与解决方案

在 Docker Registry 从 2.8 版本升级到 3.0 版本的过程中，许多用户遇到了 JWT 令牌验证失败的问题，错误信息显示"token signed by untrusted key with ID"。这个问题源于 3.0 版本中对身份验证机制的几项重要变更，特别是对 JWT 令牌验证流程的修改。

问题背景

Docker Registry 使用 JWT 令牌进行身份验证时，需要验证令牌的签名是否来自可信源。在 2.8 版本中，Registry 使用 docker/libtrust 库来生成和验证密钥 ID (kid)，而 3.0 版本改用 go-jose/go-jose 库，这带来了几个关键变化：

1. 密钥 ID 生成算法变更：libtrust 使用特定的非标准格式生成 kid，而 go-jose 使用标准 JWK 格式
2. 验证顺序调整：2.8 版本优先检查证书链，3.0 版本优先检查 JWT 令牌
3. 配置方式变化：3.0 版本需要显式配置信任的密钥集

技术细节分析

在 JWT 标准中，头部可以包含一个可选的 kid 字段，用于指示用于签名验证的密钥。3.0 版本对此的处理更加严格：

1. 如果令牌包含 kid，Registry 会先在配置的信任密钥集中查找匹配的密钥
2. 如果没有配置信任密钥集或找不到匹配的 kid，验证会失败
3. 即使配置了 rootcertbundle，也不会自动信任其中的密钥

这种变化导致了许多现有认证服务器的兼容性问题，特别是那些使用 libtrust 生成 kid 的服务器。

解决方案

对于遇到此问题的用户，有以下几种解决方案：

1. 使用 JWKS 配置：在 Registry 配置中明确指定信任的密钥集

   • 将认证服务器的公钥转换为 JWK 格式
   • 创建包含这些密钥的 JWKS 文件
   • 在 Registry 配置中添加 jwks 参数指向该文件

2. 修改认证服务器：

   • 移除 JWT 中的 kid 头部
   • 或者确保 kid 与 Registry 配置中的信任密钥匹配
   • 添加 x5c 头部包含证书链

3. 代码级解决方案：

   • 等待官方合并修复逻辑错误的 PR
   • 自行构建包含修复的 Registry 版本

最佳实践建议

对于计划升级到 3.0 版本的用户，建议采取以下步骤：

1. 评估现有认证服务器的兼容性
2. 准备 JWKS 配置文件或更新认证服务器
3. 在测试环境充分验证
4. 监控升级后的认证日志，确保没有异常

对于新部署，建议直接使用 3.0 版本的设计模式，明确配置所有信任关系，避免依赖隐式的信任机制。

总结

Docker Registry 3.0 对 JWT 验证机制的修改提高了安全性和明确性，但也带来了升级兼容性挑战。理解这些变化的技术背景和解决方案，可以帮助运维人员顺利完成升级过渡，构建更加健壮安全的容器镜像仓库系统。