hass-oidc-auth与主流身份提供商集成指南：Authentik/Authelia/Keycloak配置详解

hass-oidc-auth与主流身份提供商集成指南：Authentik/Authelia/Keycloak配置详解

【免费下载链接】hass-oidc-authOpenID Connect authentication provider for Home Assistant项目地址: https://gitcode.com/gh_mirrors/ha/hass-oidc-auth

Home Assistant作为智能家居的核心平台，安全便捷的身份验证机制至关重要。hass-oidc-auth项目为Home Assistant提供了专业的OpenID Connect身份验证集成方案，让您能够与主流身份提供商无缝对接，实现企业级单点登录体验。本指南将详细介绍如何将hass-oidc-auth与Authentik、Authelia和Keycloak三大主流身份提供商进行集成配置，帮助您快速搭建安全可靠的智能家居身份验证系统。

🚀 为什么选择hass-oidc-auth？

hass-oidc-auth是一个专门为Home Assistant设计的OpenID Connect客户端实现，具有以下核心优势：

• 企业级安全性：严格遵循OIDC规范，支持PKCE、JWT等安全标准
• 稳定可靠：最小化对Home Assistant核心代码的修改，确保系统更新兼容性
• 易于配置：提供UI和YAML两种配置方式，适合不同技术水平的用户
• 多提供商支持：兼容Authentik、Authelia、Keycloak等主流身份提供商
• 角色管理：支持基于用户组的权限控制，实现精细化管理

📦 安装准备

在开始配置之前，您需要先安装hass-oidc-auth组件。推荐通过HACS（Home Assistant社区商店）进行安装：

1. 确保已安装HACS集成
2. 在HACS中搜索"OpenID Connect"
3. 点击安装并重启Home Assistant

安装完成后，您可以在custom_components/auth_oidc/目录下找到相关文件，包括核心配置文件__init__.py和配置流程文件config_flow.py。

🔧 Authentik集成配置

Authentik是一款功能强大的开源身份提供商，支持多种认证协议。以下是详细的集成步骤：

第一步：在Authentik中创建应用

1. 登录Authentik管理界面，导航到Applications > Applications
2. 点击Create with Provider创建应用和提供商对
3. 选择OAuth2/OpenID Connect作为提供商类型
4. 配置以下关键信息：
   • Client ID：记录此值，后续需要用到
   • Redirect URI：设置为https://<您的HA地址>/auth/oidc/callback
   • 签名密钥：选择任意可用密钥（使用RS256算法）

第二步：Home Assistant配置

1. 打开Home Assistant，进入设置 > 设备与服务
2. 点击添加集成，搜索"OpenID Connect/SSO Authentication"
3. 选择"Authentik"作为提供商
4. 设置发现URL为：

   https://<您的Authentik地址>/application/o/<应用slug>/.well-known/openid-configuration

5. 输入从Authentik获取的Client ID和Client Secret
6. 配置用户组和角色映射（可选）
7. 完成配置并测试登录

配置示例（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配置

1. 在Home Assistant中添加OpenID Connect集成
2. 选择"Authelia"作为提供商
3. 设置发现URL为：

   https://<您的Authelia地址>/.well-known/openid-configuration

4. 根据Authelia配置类型填写Client ID和Client Secret
5. 完成用户链接和角色配置

高级配置选项

您可以在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客户端配置

1. 登录Keycloak管理控制台，选择要使用的Realm
2. 导航到Clients，点击Create client
3. 配置客户端：
   • Client ID：homeassistant（或自定义名称）
   • Client Authentication：根据需求开启（机密客户端）或关闭（公共客户端）
   • Valid redirect URIs：https://<您的HA地址>/auth/oidc/callback

第二步：用户组映射配置

Keycloak默认不发送用户组信息，需要手动配置组映射器：

1. 在Keycloak中进入Client Scopes
2. 创建名为groups的作用域并设置为默认作用域
3. 在作用域的Mappers标签页中创建Group Membership映射器：
   • Name：groups
   • Token Claim Name：groups
   • Full group path：OFF（重要！）
   • Add to ID token：ON
   • Add to access token：ON
   • Add to userinfo：ON

第三步：Home Assistant配置

UI配置方式（简单）

1. 在Home Assistant中添加OpenID Connect集成
2. 选择"OpenID Connect (SSO)"
3. 填写发现URL：

   https://<您的Keycloak地址>/realms/<您的Realm>/.well-known/openid-configuration

4. 输入Client ID和Client Secret

YAML配置方式（支持组映射）

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_redirect=true参数。

HTTPS强制配置

如果遇到HTTPS相关问题，可以强制启用HTTPS：

auth_oidc: features: force_https: true

常见问题解决

1. 发现URL测试失败

• 检查网络连接，确保Home Assistant可以访问您的身份提供商
• 验证URL格式是否正确
• 确认身份提供商服务正常运行

2. 用户组映射不生效

• 确认在身份提供商中正确配置了组映射
• 检查claims配置是否正确
• 验证组名称是否与roles配置中的名称完全匹配

3. 登录后权限不正确

• 检查用户是否被分配到正确的组
• 验证roles配置中的组名称
• 查看Home Assistant日志获取详细错误信息

重新配置集成

如果您需要修改集成配置，可以在集成设置中点击重新配置图标：

📋 配置对比表

🎯 最佳实践建议

1. 安全第一：始终使用HTTPS，定期更新证书
2. 备份配置：在修改配置前备份configuration.yaml文件
3. 测试环境：先在测试环境中验证配置，再应用到生产环境
4. 监控日志：定期检查Home Assistant日志，及时发现并解决问题
5. 权限最小化：按照最小权限原则分配用户角色

🔄 维护与更新

hass-oidc-auth项目持续更新，建议定期：

1. 通过HACS检查更新
2. 查看项目文档更新：docs/configuration.md
3. 关注安全公告和版本发布说明
4. 测试新版本在测试环境中的兼容性

💡 总结

通过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