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社区商店）进行安装：

确保已安装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 ID：homeassistant（或自定义名称）
- Client Authentication：根据需求开启（机密客户端）或关闭（公共客户端）
- Valid redirect URIs：https://<您的HA地址>/auth/oidc/callback

第二步：用户组映射配置

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

在Keycloak中进入Client Scopes
创建名为groups的作用域并设置为默认作用域
在作用域的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配置方式（简单）

在Home Assistant中添加OpenID Connect集成
选择"OpenID Connect (SSO)"

填写发现URL：

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

输入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日志获取详细错误信息

重新配置集成

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

📋 配置对比表

特性	Authentik	Authelia	Keycloak
安装复杂度	中等	简单	复杂
功能完整性	高	中等	非常高
企业特性	丰富	基础	全面
组映射支持	✅	✅	✅（需额外配置）
UI配置支持	✅	✅	✅
YAML配置	✅	✅	✅
推荐场景	中型企业	个人/小型团队	大型企业