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），官方文档记录的测试版本组合如下：

组件	版本
Authelia	v4.39.24
Home Assistant Application	v2025.4.2
Home Assistant 集成插件`hass-oidc-auth`	v0.6.2-alpha

其中 Home Assistant 端的 OIDC 能力并非内置，而是由第三方 HACS 插件 [OpenID Connect for Home Assistant HACS Plugin]（hass-oidc-auth）提供，本文假定你已经通过 HACS（Home Assistant Community Store）安装该插件。

前置假设

官方示例基于以下假设值，你可以根据实际部署环境替换：

Application Root URL：https://home-assistant.example.com/
Authelia Root URL：https://auth.example.com/
Client ID：home-assistant
Client Secret：insecure_secret

本文出现的example.com等占位值仅用于演示。文档站点支持通过 sitevar 变量自动替换这些占位值，实际部署时请替换为你自己的域名。

配置前的必读事项

在开始配置之前，有几个 OpenID Connect 1.0 客户端注册的通用要点需要先明确（出自官方 OIDC 集成文档的公共短代码模板 oidc-common.html）：

client_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.yml：

identity_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_secret：Authelia 与 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'：强制启用 PKCE（Proof Key for Code Exchange，RFC 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或httpsscheme），Home Assistant 的回调地址为https://home-assistant.example.com/auth/oidc/callback。不在列表中的回调将被视为不安全而拒绝。
scopes：允许该客户端消费的 scope 列表，此处为openid、profile、groups。其中groupsscope 会在 ID Token 与 UserInfo 响应中携带用户所属组列表（详见 Scope Definitions），Home Assistant 依靠它做角色映射。
response_types：code即授权码流程（Authorization Code Flow），官方安全建议是只用code，其他响应类型安全性较低。
grant_types：authorization_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_method：client_secret_post，即客户端在令牌端点通过 HTTP POST 请求体携带密钥进行认证。可选值还包括client_secret_basic（HTTP Basic 认证，confidential 客户端默认）、client_secret_jwt、private_key_jwt和none（public 客户端默认），详见 Client Authentication Method。

各 scope 在流程中的实际作用

从 OpenID Connect 1.0 Claims 指南可以确认，openid是 OIDC 流程的必需 scope；profile携带用户档案类标准声明；groups通过groupsclaim（array[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_url：Authelia 的 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_secret，PBKDF2 工作因子过高会拖慢每次认证。可先测量耗时（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 完整填写。

企业官网建设流程全解析