Leantime与Keycloak集成中的重定向问题解决方案

问题背景

在使用Leantime项目管理工具时，许多用户尝试将其与Keycloak身份认证服务进行集成，希望通过OpenID Connect(OIDC)协议实现单点登录功能。然而在实际配置过程中，经常会出现浏览器陷入无限重定向循环的问题，最终导致"页面重定向过多"的错误提示。

问题现象

当用户按照常规方式配置Leantime的OIDC参数后，点击登录按钮会观察到以下行为：

1. 浏览器开始一系列302和303状态码的重定向
2. 最终浏览器报错"页面重定向不正确"
3. 检查Keycloak管理界面发现用户实际上已经成功认证
4. Leantime的日志中并未显示明显的错误信息

根本原因分析

经过技术社区的研究和讨论，发现这个问题主要由以下几个因素导致：

1. Keycloak客户端配置不完整：特别是"Home URL"和"Valid redirect URIs"等关键参数未正确设置
2. Leantime回调URL处理：系统对认证后的回调处理逻辑存在缺陷
3. OIDC协议参数匹配：客户端和服务端之间的协议参数不完全一致

解决方案

Keycloak端配置要点

在Keycloak管理控制台中，为Leantime客户端配置以下关键参数：

Root URL: https://leantime.yourdomain.com
Home URL: https://leantime.yourdomain.com
Valid redirect URIs: https://leantime.yourdomain.com/*
Valid post logout redirect URIs: https://leantime.yourdomain.com
Admin URL: https://leantime.yourdomain.com

特别注意：

• Home URL必须明确指定，这是许多配置遗漏的关键点
• 重定向URI需要使用通配符(*)确保所有子路径都被包含
• 所有URL必须使用HTTPS协议(除非在开发环境中明确使用HTTP)

Leantime环境变量配置

在Leantime的.env配置文件中，需要设置以下OIDC相关参数：

# 启用OIDC功能
LEAN_OIDC_ENABLE=true

# Keycloak客户端ID和密钥
LEAN_OIDC_CLIENT_ID=leantime
LEAN_OIDC_CLIENT_SECRET=your_client_secret

# Keycloak提供者URL(包含realm路径)
LEAN_OIDC_PROVIDER_URL=https://keycloak.yourdomain.com/realms/your-realm

# 自动创建用户选项
LEAN_OIDC_CREATE_USER=true

# 新用户的默认角色(20表示编辑者)
LEAN_OIDC_DEFAULT_ROLE=20

其他注意事项

1. 协议一致性：确保Keycloak和Leantime都使用相同的协议(HTTP/HTTPS)
2. 域名解析：所有使用的域名必须能够正确解析
3. 会话超时：检查Keycloak和Leantime的会话超时设置是否协调
4. Cookie设置：确保浏览器允许设置来自两个域名的Cookie

验证步骤

完成上述配置后，可以通过以下步骤验证集成是否成功：

1. 清除浏览器缓存和Cookie
2. 访问Leantime登录页面
3. 点击"OIDC登录"按钮
4. 观察是否正常跳转到Keycloak登录页面
5. 输入有效凭证后，应直接跳转回Leantime并显示已登录状态

总结

Leantime与Keycloak的OIDC集成虽然看似简单，但细节配置往往决定成败。通过本文提供的配置方案，大多数重定向循环问题都能得到解决。对于更复杂的部署环境，建议分阶段调试：先确保Keycloak端配置正确，再调整Leantime参数，最后处理网络和会话相关设置。