Homarr与Authentik实现无缝SSO登录的技术方案

背景介绍

Homarr是一款开源的仪表盘工具，而Authentik则是一个功能强大的开源身份认证和访问管理平台。在实际部署中，许多用户希望将两者结合使用，实现单点登录(SSO)功能。本文将详细介绍如何配置Homarr与Authentik的OIDC集成，并实现自动跳转至Authentik登录页面的优化方案。

OIDC集成基础配置

Homarr支持通过OpenID Connect(OIDC)协议与Authentik进行集成。基础配置需要在Homarr的环境变量中设置以下参数：

• AUTH_OIDC_ENABLED="true"：启用OIDC认证
• AUTH_OIDC_PROVIDER_NAME="Authentik"：设置提供商名称
• AUTH_OIDC_CLIENT_ID：配置客户端ID
• AUTH_OIDC_CLIENT_SECRET：配置客户端密钥
• AUTH_OIDC_ISSUER：设置认证服务器地址

完成这些基础配置后，用户可以在Homarr的登录页面看到"Sign In - Authentik"的选项，点击后会被重定向到Authentik进行认证。

自动跳转优化方案

默认配置下，用户需要先访问Homarr登录页面，再点击按钮跳转到Authentik。这种两步操作流程不够简洁。通过设置环境变量：

AUTH_OIDC_AUTO_LOGIN="true"

可以实现以下优化效果：

1. 当用户访问Homarr时，系统会自动检测OIDC配置
2. 若检测到有效的OIDC配置且启用了自动登录，将直接重定向到Authentik登录页面
3. 如果用户已在Authentik中登录，系统会自动完成认证并返回Homarr仪表盘
4. 整个过程无需用户手动点击任何按钮，实现真正的无缝登录体验

技术实现原理

这种自动跳转功能的实现基于OIDC协议的标准流程：

1. 客户端(Homarr)检测到未认证请求
2. 根据配置生成包含客户端ID、回调地址等参数的认证请求
3. 通过302重定向将用户浏览器指向Authentik的授权端点
4. Authentik处理认证请求，可能展示登录页面或直接颁发令牌
5. 用户被重定向回Homarr的回调地址完成会话建立

部署注意事项

1. 确保Homarr和Authentik之间的网络连通性
2. 在Authentik中正确配置回调URL
3. 考虑启用HTTPS以确保认证过程的安全性
4. 测试不同场景下的登录流程，包括首次登录、已登录和会话过期等情况
5. 监控日志以确保认证流程正常工作

总结

通过简单的环境变量配置，Homarr可以实现与Authentik的无缝OIDC集成，大幅提升用户体验。这种方案不仅简化了登录流程，还增强了系统的安全性，是企业级部署的理想选择。