Homarr项目OIDC认证重定向问题分析与解决方案

问题背景

Homarr是一款基于Docker的开源仪表板工具，在0.15.0版本中引入了OIDC(OpenID Connect)认证功能。然而，许多用户在使用过程中遇到了重定向URL不正确的问题，主要表现为系统错误地将请求重定向到localhost而非配置的外部域名。

问题现象

用户报告的主要症状包括：

1. 配置了外部域名(如https://homarr.example.com)作为重定向URL，但系统实际发送的请求中包含http://localhost:7575
2. 认证失败后返回错误信息"Invalid callback URL"
3. 在Keycloak或Authentik等认证提供者端收到不匹配的重定向URI错误

技术分析

这个问题源于Homarr在构建重定向URL时未能正确处理反向代理后的环境。具体原因包括：

1. X-Forwarded头处理不完善：系统未能正确识别反向代理设置的各种X-Forwarded头信息
2. 多协议处理问题：当X-Forwarded-Proto头包含多个协议(如"https,http")时，系统处理不当
3. URL路径拼接错误：在构建完整URL时出现了多余的斜杠和路径拼接问题
4. 环境变量优先级：NEXTAUTH_URL环境变量的使用方式需要优化

解决方案

开发团队通过以下方式解决了该问题：

1. 完善协议处理逻辑：当X-Forwarded-Proto包含多个协议时，优先选择https
2. 修正URL构建方式：确保路径拼接时不产生多余的斜杠
3. 优化环境变量使用：明确NEXTAUTH_URL的作用范围和优先级

配置建议

对于使用反向代理的用户，建议采用以下配置：

Docker环境变量配置

AUTH_PROVIDER=oidc
AUTH_OIDC_URI=https://auth.example.com/application/o/homarr
AUTH_OIDC_CLIENT_ID=your_client_id
AUTH_OIDC_CLIENT_SECRET=your_client_secret
AUTH_OIDC_CLIENT_NAME=YourAuthProvider
NEXTAUTH_URL=https://homarr.example.com

反向代理配置(Nginx示例)

location / {
    proxy_pass http://homarr-container:7575;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_cache_bypass $http_upgrade;
}

认证提供者配置要点

1. 重定向URL应设置为：https://homarr.example.com/api/auth/callback/oidc
2. 注意不要包含结尾斜杠
3. 在Authentik中，签名密钥应选择"authentik Self-signed Certificate"
4. 重定向URI可以使用通配符".*"简化配置

版本更新

该修复已包含在0.15.1版本中。用户可以通过以下方式获取修复：

1. 使用最新稳定版镜像
2. 或使用临时修复标签：fix-redirect-oidc

常见问题排查

如果问题仍然存在，建议检查：

1. 确保使用最新镜像(sha256:1b0e36984570090ce75ddb1a066b4bbba34d50d83175c1da4a64eaf4e74dfd74)
2. 验证反向代理头信息是否正确传递
3. 检查认证提供者端的重定向URL配置
4. 确认环境变量设置无误

总结

OIDC认证是现代应用的重要安全特性，Homarr通过这次修复完善了对反向代理环境的支持，使系统能够更可靠地在生产环境中部署。用户只需按照推荐的配置方式，即可实现安全的单点登录功能。