Leantime项目OIDC集成中的JWT解码问题分析与解决方案

问题背景

在Leantime项目管理系统中集成Authentik作为OIDC身份提供商时，开发者遇到了两个关键的技术问题：无限重定向循环和JWT令牌解码失败。这些问题在Docker容器化部署环境中尤为常见，特别是在使用Nginx反向代理的情况下。

问题现象分析

无限重定向循环

当用户点击"OIDC登录"按钮时，系统会正确重定向到Authentik认证页面，但随后陷入无限重定向循环。每次循环都会在Authentik服务器上留下日志记录，表明认证流程已启动但未能完成。

JWT解码错误

在后续尝试中，系统报告了两种不同的JWT相关错误：

1. "Undefined array key 'kid'" - 表明系统在解析JWT令牌时无法找到预期的密钥标识符
2. "JWT token could not be decoded" - 表明系统完全无法解码收到的JWT令牌

根本原因

经过深入分析，这些问题主要源于以下几个技术因素：

1. JWT签名配置不当：Authentik默认可能使用加密签名，而Leantime期望的是非加密的简单签名验证
2. 反向代理配置：Nginx Proxy Manager可能修改了关键的HTTP头信息，影响了OIDC流程
3. 环境变量处理：PHP对特殊字符的处理可能导致OIDC配置参数被错误解析
4. 证书配置：Authentik中的SSL证书设置可能与Leantime的期望不匹配

解决方案

1. Authentik提供方配置调整

在Authentik管理界面中，确保以下配置：

• 将"Subject Mode"设置为"基于用户ID的哈希"
• 移除所有签名密钥和加密密钥设置（除非确实需要）
• 检查SSL证书配置，尝试暂时禁用以测试是否为证书问题

2. Leantime环境变量优化

在Leantime的.env配置文件中，确保OIDC相关参数使用引号包裹：

LEAN_OIDC_CLIENT_ID='your_client_id'
LEAN_OIDC_CLIENT_SECRET='your_client_secret'

3. 反向代理配置检查

确认Nginx Proxy Manager的配置：

• 确保3081端口正确映射
• 保留必要的HTTP头信息（如Authorization）
• 检查是否有重写规则干扰了OIDC回调

4. 系统升级与调试

• 确保使用最新版本的Leantime（3.3.3或更高）
• 启用调试模式（LEAN_DEBUG=1）以获取更详细的错误信息
• 检查存储目录权限，确保可以写入会话数据

最佳实践建议

1. 分阶段测试：先在不加密的情况下测试基本功能，再逐步添加安全层
2. 日志分析：同时检查Leantime和Authentik两端的日志以定位问题环节
3. 最小化配置：从最简单的配置开始，逐步添加复杂度
4. 网络拓扑：确保所有服务之间的网络连接畅通，特别是Docker容器间的通信

总结

Leantime与Authentik的OIDC集成问题通常源于配置不匹配而非代码缺陷。通过系统性地检查各环节配置，特别是JWT处理方式和反向代理设置，大多数问题都可以得到解决。对于生产环境，建议在解决基本功能后，再逐步实施更严格的安全措施，如JWT加密和严格的证书验证。