hass-oidc-auth与主流身份提供商集成指南Authentik/Authelia/Keycloak配置详解【免费下载链接】hass-oidc-authOpenID Connect authentication provider for Home Assistant项目地址: https://gitcode.com/gh_mirrors/ha/hass-oidc-authHome Assistant作为智能家居的核心平台安全便捷的身份验证机制至关重要。hass-oidc-auth项目为Home Assistant提供了专业的OpenID Connect身份验证集成方案让您能够与主流身份提供商无缝对接实现企业级单点登录体验。本指南将详细介绍如何将hass-oidc-auth与Authentik、Authelia和Keycloak三大主流身份提供商进行集成配置帮助您快速搭建安全可靠的智能家居身份验证系统。 为什么选择hass-oidc-authhass-oidc-auth是一个专门为Home Assistant设计的OpenID Connect客户端实现具有以下核心优势企业级安全性严格遵循OIDC规范支持PKCE、JWT等安全标准稳定可靠最小化对Home Assistant核心代码的修改确保系统更新兼容性易于配置提供UI和YAML两种配置方式适合不同技术水平的用户多提供商支持兼容Authentik、Authelia、Keycloak等主流身份提供商角色管理支持基于用户组的权限控制实现精细化管理 安装准备在开始配置之前您需要先安装hass-oidc-auth组件。推荐通过HACSHome Assistant社区商店进行安装确保已安装HACS集成在HACS中搜索OpenID Connect点击安装并重启Home Assistant安装完成后您可以在custom_components/auth_oidc/目录下找到相关文件包括核心配置文件__init__.py和配置流程文件config_flow.py。 Authentik集成配置Authentik是一款功能强大的开源身份提供商支持多种认证协议。以下是详细的集成步骤第一步在Authentik中创建应用登录Authentik管理界面导航到Applications Applications点击Create with Provider创建应用和提供商对选择OAuth2/OpenID Connect作为提供商类型配置以下关键信息Client ID记录此值后续需要用到Redirect URI设置为https://您的HA地址/auth/oidc/callback签名密钥选择任意可用密钥使用RS256算法第二步Home Assistant配置打开Home Assistant进入设置 设备与服务点击添加集成搜索OpenID Connect/SSO Authentication选择Authentik作为提供商设置发现URL为https://您的Authentik地址/application/o/应用slug/.well-known/openid-configuration输入从Authentik获取的Client ID和Client Secret配置用户组和角色映射可选完成配置并测试登录配置示例YAML方式如果您更喜欢使用YAML配置可以在configuration.yaml中添加auth_oidc: client_id: your_authentik_client_id discovery_url: https://authentik.example.com/application/o/app-slug/.well-known/openid-configuration display_name: Authentik SSO Authelia集成配置Authelia是一款轻量级的开源身份验证和授权服务器特别适合自托管环境。第一步Authelia配置根据您的需求选择公共客户端或机密客户端配置公共客户端配置推荐# Authelia configuration.yml identity_providers: oidc: clients: - client_id: homeassistant client_name: Home Assistant public: true require_pkce: true pkce_challenge_method: S256 redirect_uris: - https://hass.example.com/auth/oidc/callback机密客户端配置identity_providers: oidc: clients: - client_id: homeassistant client_name: Home Assistant client_secret: your_secure_secret public: false require_pkce: true pkce_challenge_method: S256 redirect_uris: - https://hass.example.com/auth/oidc/callback token_endpoint_auth_method: client_secret_post第二步Home Assistant配置在Home Assistant中添加OpenID Connect集成选择Authelia作为提供商设置发现URL为https://您的Authelia地址/.well-known/openid-configuration根据Authelia配置类型填写Client ID和Client Secret完成用户链接和角色配置高级配置选项您可以在configuration.yaml中进一步定制Authelia集成auth_oidc: client_id: homeassistant discovery_url: https://authelia.example.com/.well-known/openid-configuration id_token_signing_alg: RS256 claims: display_name: name username: preferred_username groups: groups roles: admin: administrators user: users Keycloak集成配置Keycloak是企业级的开源身份和访问管理解决方案功能最为全面。第一步Keycloak客户端配置登录Keycloak管理控制台选择要使用的Realm导航到Clients点击Create client配置客户端Client IDhomeassistant或自定义名称Client Authentication根据需求开启机密客户端或关闭公共客户端Valid redirect URIshttps://您的HA地址/auth/oidc/callback第二步用户组映射配置Keycloak默认不发送用户组信息需要手动配置组映射器在Keycloak中进入Client Scopes创建名为groups的作用域并设置为默认作用域在作用域的Mappers标签页中创建Group Membership映射器NamegroupsToken Claim NamegroupsFull group pathOFF重要Add to ID tokenONAdd to access tokenONAdd to userinfoON第三步Home Assistant配置UI配置方式简单在Home Assistant中添加OpenID Connect集成选择OpenID Connect (SSO)填写发现URLhttps://您的Keycloak地址/realms/您的Realm/.well-known/openid-configuration输入Client ID和Client SecretYAML配置方式支持组映射auth_oidc: client_id: homeassistant client_secret: !secret oidc_client_secret # 如果Keycloak中启用了客户端认证 discovery_url: https://keycloak.example.com/realms/master/.well-known/openid-configuration roles: user: homeassistant # 普通用户组 admin: homeassistantadmin # 管理员组️ 通用配置技巧与故障排除跳过欢迎屏幕如果您希望直接跳转到OIDC登录页面可以配置auth_oidc: features: default_redirect: true配置后如需使用备用登录方式可在URL后添加?skip_oidc_redirecttrue参数。HTTPS强制配置如果遇到HTTPS相关问题可以强制启用HTTPSauth_oidc: features: force_https: true常见问题解决1. 发现URL测试失败检查网络连接确保Home Assistant可以访问您的身份提供商验证URL格式是否正确确认身份提供商服务正常运行2. 用户组映射不生效确认在身份提供商中正确配置了组映射检查claims配置是否正确验证组名称是否与roles配置中的名称完全匹配3. 登录后权限不正确检查用户是否被分配到正确的组验证roles配置中的组名称查看Home Assistant日志获取详细错误信息重新配置集成如果您需要修改集成配置可以在集成设置中点击重新配置图标 配置对比表特性AuthentikAutheliaKeycloak安装复杂度中等简单复杂功能完整性高中等非常高企业特性丰富基础全面组映射支持✅✅✅需额外配置UI配置支持✅✅✅YAML配置✅✅✅推荐场景中型企业个人/小型团队大型企业 最佳实践建议安全第一始终使用HTTPS定期更新证书备份配置在修改配置前备份configuration.yaml文件测试环境先在测试环境中验证配置再应用到生产环境监控日志定期检查Home Assistant日志及时发现并解决问题权限最小化按照最小权限原则分配用户角色 维护与更新hass-oidc-auth项目持续更新建议定期通过HACS检查更新查看项目文档更新docs/configuration.md关注安全公告和版本发布说明测试新版本在测试环境中的兼容性 总结通过hass-oidc-auth您可以轻松将Home Assistant与Authentik、Authelia或Keycloak等主流身份提供商集成实现企业级的单点登录体验。无论您选择哪种方案都能获得安全、稳定且易于管理的身份验证解决方案。记住正确的配置是安全的基础。花时间仔细配置每个步骤确保您的智能家居系统既便捷又安全。如有疑问可以参考项目提供的详细文档或社区讨论获取帮助。现在开始享受统一身份验证带来的便利吧【免费下载链接】hass-oidc-authOpenID Connect authentication provider for Home Assistant项目地址: https://gitcode.com/gh_mirrors/ha/hass-oidc-auth创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考