Authelia 与 Home Assistant 的 OpenID Connect 1.0 单点登录集成指南

Authelia 与 Home Assistant 的 OpenID Connect 1.0 单点登录集成指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia本篇技术指南以 Authelia 官方集成文档为骨架完整讲解如何将智能家居平台 Home Assistant 注册为 Authelia OpenID Connect 1.0 Provider 的客户端实现通过 Authelia 统一登录与双因子认证2FA访问 Home Assistant。读完本文你将掌握在 Authelia 的configuration.yml中注册 OIDC 客户端、在 Home Assistant 的configuration.yaml中配置auth_oidc模块、并通过groupsscope 将 Authelia 用户组映射为 Home Assistant 管理员角色的完整实战方案。集成概览与版本基线该集成方案由社区提供并经过官方验证support 级别为 community官方文档记录的测试版本组合如下组件版本Autheliav4.39.24Home Assistant Applicationv2025.4.2Home Assistant 集成插件hass-oidc-authv0.6.2-alpha其中 Home Assistant 端的 OIDC 能力并非内置而是由第三方 HACS 插件 [OpenID Connect for Home Assistant HACS Plugin]hass-oidc-auth提供本文假定你已经通过 HACSHome Assistant Community Store安装该插件。前置假设官方示例基于以下假设值你可以根据实际部署环境替换Application Root URLhttps://home-assistant.example.com/Authelia Root URLhttps://auth.example.com/Client IDhome-assistantClient Secretinsecure_secret本文出现的example.com等占位值仅用于演示。文档站点支持通过 sitevar 变量自动替换这些占位值实际部署时请替换为你自己的域名。配置前的必读事项在开始配置之前有几个 OpenID Connect 1.0 客户端注册的通用要点需要先明确出自官方 OIDC 集成文档的公共短代码模板 oidc-common.htmlclient_id的要求每个客户端的client_id必须是全局唯一的值文档中的示例值仅用于可读性与演示生产环境不应直接使用建议使用随机生成的长字符串官方推荐 64 个随机字符只能包含 RFC3986 Unreserved Characters即大小写字母、数字以及-、.、_、~长度不能超过 100 个字符。client_secret的要求示例中的明文insecure_secret仅用于演示生产环境必须替换为随机生成的高强度密钥明文存储在 Authelia 配置中属于已被弃用的行为官方强烈建议在配置中存放密钥的哈希值详见 Frequently Asked Questions 的 Plaintext 条目若使用哈希存储过高的哈希工作因子可能导致客户端认证超时需要根据硬件能力调整。配置完整性下面给出的 Authelia 配置片段只包含客户端注册部分你还必须同时完成 OpenID Connect 1.0 Provider Configuration 中要求的其他必填配置项客户端可配置项远不止示例中的这些建议通读 OpenID Connect 1.0 Clients Configuration 了解全部选项及其影响。生成真实的客户端标识与密钥官方推荐用 Authelia 自带的随机生成器来产生生产级凭证具体做法见 Frequently Asked Questions 与 Generating Secure Values 参考指南# 生成 72 字符的客户端 ID仅含 RFC3986 无保留字符 authelia crypto rand --length 72 --charset rfc3986 # 生成 72 字符的客户端密钥并直接输出 PBKDF2 哈希供 Authelia 配置使用 authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986使用 Docker 部署时在上述命令前加上docker run --rm authelia/authelia:latest即可。如果客户端在访问令牌端点时因字符编码问题报错可以调高随机字符集的选择范围官方随机密码生成器会在字符集经过 URL 编码后产生不同值时额外输出一个预编码版本供你选用。在 Authelia 中注册 Home Assistant 客户端Authelia 作为 OpenID Connect 1.0 Provider通过 OpenID Connect 1.0 Clients 中的identity_providers.oidc.clients列表注册依赖方Relying Party客户端。将以下片段加入 Authelia 的configuration.ymlidentity_providers: oidc: ## OpenID Connect 1.0 Provider 的其他必填配置项在此填写。 ## 参见: docs/content/configuration/identity-providers/openid-connect/provider.md clients: - client_id: home-assistant client_name: Home Assistant client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # The digest of insecure_secret. public: false require_pkce: true pkce_challenge_method: S256 authorization_policy: two_factor redirect_uris: - https://home-assistant.example.com/auth/oidc/callback scopes: - openid - profile - groups response_types: - code grant_types: - authorization_code access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_post各配置项含义与取值说明client_id客户端唯一标识必须与 Home Assistant 端配置的client_id完全一致。client_name显示在 Authelia 用户界面中的友好名称默认与client_id相同。client_secretAuthelia 与 Home Assistant 之间的共享密钥。示例中存放的是insecure_secret的pbkdf2-sha512哈希摘要这是官方推荐的做法Home Assistant 端则配置明文密钥。需要说明的是配置哈希密钥时认证请求的耗时取决于哈希工作因子若客户端操作超时可参考 Tuning the work factors 降低迭代次数示例为310000。public: false声明为机密confidential客户端类型即客户端有能力安全保存凭证必须提供client_secret。若设置为true公开客户端适用于 SPA、CLI 工具则client_secret必须为空字符串。require_pkce: true与pkce_challenge_method: S256强制启用 PKCEProof Key for Code ExchangeRFC 7636并强制使用S256挑战方法。PKCE 通过将随机code_verifier的 SHA-256 摘要作为code_challenge绑定授权码可有效缓解授权码拦截攻击S256是官方强烈推荐的方法plain仅应在客户端无法支持时使用。对应的全局开关是 Provider 配置中的 enforce_pkce。authorization_policy: two_factor该客户端授权请求所需的认证策略取值为one_factor、two_factor或 Provider 中 authorization_policies 定义的策略名。two_factor意味着用户必须以双因子方式登录后才能完成 OIDC 授权。redirect_uris允许回调的 URI 列表大小写敏感必须包含http或httpsschemeHome Assistant 的回调地址为https://home-assistant.example.com/auth/oidc/callback。不在列表中的回调将被视为不安全而拒绝。scopes允许该客户端消费的 scope 列表此处为openid、profile、groups。其中groupsscope 会在 ID Token 与 UserInfo 响应中携带用户所属组列表详见 Scope DefinitionsHome Assistant 依靠它做角色映射。response_typescode即授权码流程Authorization Code Flow官方安全建议是只用code其他响应类型安全性较低。grant_typesauthorization_code授权码授权类型。注意该列表决定客户端能否访问令牌端点获取令牌。access_token_signed_response_alg/userinfo_signed_response_alg均为none表示访问令牌与 UserInfo 响应不做 JWT 签名以普通 JSON 返回。Authelia 默认即为不透明访问令牌非 JWT只有配置了非none值才会启用 RFC9068 JWT Profile Access Token。token_endpoint_auth_methodclient_secret_post即客户端在令牌端点通过 HTTP POST 请求体携带密钥进行认证。可选值还包括client_secret_basicHTTP Basic 认证confidential 客户端默认、client_secret_jwt、private_key_jwt和nonepublic 客户端默认详见 Client Authentication Method。各 scope 在流程中的实际作用从 OpenID Connect 1.0 Claims 指南 可以确认openid是 OIDC 流程的必需 scopeprofile携带用户档案类标准声明groups通过groupsclaimarray[string]类型来源于认证后端上报的用户组成员关系将 Authelia 用户组传递到 Home Assistant 端这是下方roles.admin映射的数据来源。在 Home Assistant 中配置 OpenID Connect 登录Home Assistant 的配置方式为修改配置文件官方集成文档将该文件统称为 Configuration File一般情况下即configuration.yaml。将以下片段加入其中auth_oidc: client_id: home-assistant client_secret: insecure_secret discovery_url: https://auth.example.com/.well-known/openid-configuration display_name: Authelia roles: admin: admins配置项说明client_id必须与 Authelia 客户端配置中的client_id完全一致home-assistant。client_secret此处配置明文密钥与 Authelia 配置中存储的哈希摘要对应同一个秘密。discovery_urlAuthelia 的 OpenID Connect Discovery 端点地址即https://auth.example.com/.well-known/openid-configuration。Home Assistant 的hass-oidc-auth插件会从这里自动发现授权端点/api/oidc/authorization、令牌端点/api/oidc/token、UserInfo 端点/api/oidc/userinfo与 JWKS 等元数据因此无需手动填写各端点路径。该端点属于 IANA well-known 注册路径Authelia 同时提供 OAuth 2.0 Authorization Server Metadata/.well-known/oauth-authorization-server具体端点清单见 OpenID Connect 1.0 Integration Guide 的 Endpoint Implementations 章节。display_name在 Home Assistant 登录界面显示的提供方名称示例为Authelia。roles.admin角色映射值为 Authelia 用户组名。此处admins表示当用户属于 Authelia 的admins组时由groupsscope 携带在 Home Assistant 中拥有管理员角色。登录流程与安全特性验证完成上述两端配置并重启服务后访问 Home Assistant 的登录页面即可看到由display_name标识的 Authelia 登录入口。整体流程如下用户点击通过 Authelia 登录Home Assistant 将用户重定向到 Authelia 的授权端点Authelia 根据authorization_policy: two_factor要求用户完成双因子认证若尚未登录认证通过后Authelia 依据require_pkce/pkce_challenge_method校验 PKCE 挑战并向 Home Assistant 发放授权码Home Assistant 通过client_secret_post方式在令牌端点兑换令牌Authelia 校验client_secret的 PBKDF2 哈希Home Assistant 读取 ID Token / UserInfo 中的groups声明按roles.admin映射判断用户角色。该流程中的 PKCE、客户端认证等安全机制均可在 Authelia 源码中找到对应实现例如 handler_oauth2_authorization.go、handler_oauth2_token.go 与 handler_oauth2_oidc_userinfo.go 分别处理授权请求、令牌颁发与用户信息返回OIDC 客户端配置的解析与校验逻辑位于 internal/configuration/schema 与 internal/configuration/validator 目录相关端到端行为也有 handler_oauth2_authorization_test.go、handler_oauth2_token_test.go 等测试覆盖。常见问题与排查要点客户端标识或密钥报错请确认两端client_id/client_secret完全一致且字符仅包含 RFC3986 无保留字符。某些客户端在令牌端点未按 RFC 6749 Appendix B 对凭证做 URL 编码使用特殊字符会触发认证失败参见 oidc-common.html 中的 client-credentials-encoding 说明。登录超时若 Authelia 端配置了哈希形式的client_secretPBKDF2 工作因子过高会拖慢每次认证。可先测量耗时time authelia crypto hash generate pbkdf2 --variant sha512 --iterations 310000 --password insecure_password再按需降低迭代次数。发现端点无法访问确认discovery_url指向 Authelia 的根域名即 OIDC Issuer而非某个应用子路径同时确保 Provider 级别的 OpenID Connect 1.0 配置如issuer、签名密钥等已按 Provider Configuration 完整填写。延伸阅读Home Assistant OpenID Connect Auth 集成文档hass-oidc-authOpenID Connect 1.0 集成总览与协议细节OpenID Connect 1.0 客户端注册配置参考OpenID Connect 1.0 Provider 配置参考OpenID Connect 1.0 集成常见问题 FAQOpenID Connect 1.0 声明与 scope 定义【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考