Authelia 与 Homarr 集成指南：通过 OpenID Connect 1.0 实现统一身份认证与单点登录-港品优选

Authelia 与 Homarr 集成指南：通过 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

本指南面向希望将 Homarr 仪表盘接入 Authelia 统一认证体系的开发者，完整讲解基于 OpenID Connect 1.0（OIDC）协议的客户端注册、环境变量配置与已知缺陷规避方案。读完本文，你将掌握在 Authelia 中注册 Homarr 客户端的完整 YAML 配置、在 Homarr 侧通过环境变量启用 OIDC 登录的具体写法，以及如何利用 Authelia 的 "escape hatch"（逃生舱）机制解决 Homarr 对 OpenID Connect 1.0 支持不完整导致的 claims 获取失败问题。

文档定位与适用版本

本文对应的官方集成文档位于 docs/content/integration/openid-connect/clients/homarr/index.md，属于 Authelia 官方文档中"OpenID Connect 1.0 依赖方（Relying Party）集成"系列的一部分。该集成属于Community 级别支持（文档 frontmatter 中level: community），意味着配置由社区验证维护。

文档验证过的版本组合如下：

组件	版本
Authelia	v4.39.18
Homarr	1.59.0

需要注意的是，Homarr 通过 OpenID Connect 1.0 接入 Authelia 时，其登录流程完全交由 Authelia 处理：用户在 Authelia 门户完成认证（可含多因素认证），认证通过后由浏览器回调 Homarr 建立本地会话。Authelia 在此场景中扮演 OpenID Connect 1.0 Provider 角色，Homarr 则是 Relying Party。

已知缺陷：Homarr 的 Claims Hydration 问题

在动手配置之前，必须先了解 Homarr 集成中最关键的一个坑。官方文档通过oidc-commonshortcode（见 docs/layouts/_shortcodes/oidc-common.html）声明了该客户端存在Claims Hydration缺陷：

Homarr 完全没有按照 OpenID Connect 1.0 规范所要求的流程去获取它需要的 claims。具体来说，规范要求客户端通过 Access Token 在 UserInfo 端点获取由 scope 授权的 claims（见 OpenID Connect Core 1.0 第 5.4 节），但 Homarr 没有执行这一标准流程，导致它拿不到用户属性数据。

这一缺陷意味着 Homarr 对 OpenID Connect 1.0 的支持并不完整（non-conformant）。幸运的是，Authelia 为此类客户端实现了专用的兼容机制（escape hatch），只需在 Homarr 侧设置一个环境变量即可规避：

AUTH_OIDC_FORCE_USERINFO=true

该变量强制 Homarr 从 UserInfo 端点拉取 claims，从而绕过其对标准流程的缺失支持。其原理可参见 Authelia 官方 OpenID Connect 1.0 Claims 指南中关于 "restore functionality prior to claims parameter" 的说明：Authelia 出于隐私与安全考虑，默认仅在 ID Token 中放置最小化的授权证明 claims，其余由 scope 授权的 claims 需要通过 Access Token 在 UserInfo 端点获取；AUTH_OIDC_FORCE_USERINFO正是让 Homarr 走这条标准通道。

配置前置假设

本指南的所有示例基于以下假设值，实际部署时请替换为你的真实域名与凭据：

Homarr 应用根地址：https://homarr.example.com/
Authelia 根地址：https://auth.example.com/
Client ID：homarr
Client Secret：insecure_secret

⚠️ 安全提醒：homarr与insecure_secret仅为演示用途。生产环境中应使用随机生成的强凭据，官方强烈建议 Client ID 使用 64 位随机字符、Client Secret 使用哈希存储（见后文"通用注意事项"）。

Authelia 侧配置：注册 Homarr 为 OIDC 客户端

在 Authelia 的configuration.yml中，于identity_providers.oidc.clients下新增 Homarr 客户端注册：

identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. clients: - client_id: 'homarr' client_name: 'Homarr' client_secret: '$pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng' # The digest of 'insecure_secret'. public: false authorization_policy: 'two_factor' require_pkce: false pkce_challenge_method: '' redirect_uris: - 'https://homarr.example.com/api/auth/callback/oidc' scopes: - 'openid' - 'profile' - 'groups' - 'email' response_types: - 'code' grant_types: - 'authorization_code' access_token_signed_response_alg: 'none' userinfo_signed_response_alg: 'none' token_endpoint_auth_method: 'client_secret_basic'

各配置项详解

对上述配置的完整字段说明可参考 OpenID Connect 1.0 Clients 配置文档，这里解释与 Homarr 集成直接相关的几个关键项：

client_id：客户端唯一标识，必须与 Homarr 侧配置完全一致。官方要求其不超过 100 个字符、仅包含 RFC3986 非保留字符，且与其他客户端不重复。
client_secret：示例中给出的是insecure_secret的 PBKDF2-SHA512 哈希值（$pbkdf2-sha512$310000$...），这也是 Authelia 官方推荐的存储方式。哈希存储的代价参数（如迭代次数310000）过高时可能导致客户端认证超时，可参考 FAQ 中关于工作因子调优的说明。
public: false：声明该客户端为机密型（confidential）客户端，认证时需提供 Client Secret。
authorization_policy: 'two_factor'：登录 Homarr 需要经过两因素认证。如需仅单因素，可改为one_factor。
require_pkce: false：不强制 PKCE。PKCE 是推荐的安全增强手段，若 Homarr 支持可尝试开启并配套设置pkce_challenge_method（如S256）。
redirect_uris：授权码回调地址，必须精确匹配Homarr 的 OIDC 回调路径/api/auth/callback/oidc，否则授权流程会失败。
scopes：openid、profile、groups、email四个 scope 决定了 Homarr 能通过 UserInfo 端点获取的用户属性范围。
response_types: ['code']与grant_types: ['authorization_code']：使用标准的授权码流程（Authorization Code Flow）。
access_token_signed_response_alg: 'none'/userinfo_signed_response_alg: 'none'：Access Token 与 UserInfo 响应不签名，减少 Homarr 解析负担。
token_endpoint_auth_method: 'client_secret_basic'：Homarr 在 Token 端点使用 HTTP Basic 认证携带客户端凭据。

📌 注意：上述片段只包含客户端注册部分。identity_providers.oidc下还必须配置 Provider 级必需的其余元素（如签发者issuer等），完整 Provider 配置见 OpenID Connect 1.0 Provider 配置文档。

通用注意事项（来自官方 shortcode 模板）

根据 oidc-common.html 模板，所有 OIDC 集成都需遵循以下要点：

Client ID 必须全局唯一，仅用于演示的值不应在生产使用；建议通过 Authelia 的随机密码生成器生成，官方 FAQ 中有"如何生成 client identifier / client secret"的说明（见 frequently-asked-questions.md）。
Client Secret 可以明文存储，但该行为已被弃用，未来版本不保证继续支持；哈希存储（示例即为此形式）是强烈推荐方式。
客户端注册之外，Provider 级别的必需配置项必须另行补齐；同时本文只展示了部分可用客户端选项，生产环境建议通读完整的 Clients 配置文档了解全部选项及其效果。

Homarr 侧配置：环境变量启用 OIDC

Homarr 的 OIDC 配置只能通过环境变量完成（文档明确说明"there is one method, using the Environment Variables"）。分为标准环境变量与配置逃生舱两部分。

标准环境变量

在.env文件中配置：

AUTH_PROVIDERS=oidc AUTH_OIDC_ISSUER=https://auth.example.com AUTH_OIDC_CLIENT_ID=homarr AUTH_OIDC_CLIENT_SECRET=insecure_secret AUTH_OIDC_CLIENT_NAME=Authelia AUTH_OIDC_SCOPE_OVERWRITE=openid email profile groups AUTH_OIDC_GROUPS_ATTRIBUTE=groups AUTH_LOGOUT_REDIRECT_URL=https://auth.example.com/logout

各变量含义：

AUTH_PROVIDERS=oidc：启用 OIDC 作为认证提供方。
AUTH_OIDC_ISSUER：Authelia 的签发者地址，即 Authelia 的根 URL（不带末尾斜杠），Homarr 会据此自动发现 Authelia 的 OpenID 配置端点。
AUTH_OIDC_CLIENT_ID/AUTH_OIDC_CLIENT_SECRET：与 Authelia 侧client_id/client_secret完全一致的凭据。注意 Homarr 侧使用明文secret，而 Authelia 配置中可存储其哈希值。
AUTH_OIDC_CLIENT_NAME=Authelia：在 Homarr 登录页展示的提供方名称。
AUTH_OIDC_SCOPE_OVERWRITE=openid email profile groups：覆盖默认请求的 scope 列表，与 Authelia 注册的scopes对应，确保 Homarr 能请求到 groups 等额外属性。
AUTH_OIDC_GROUPS_ATTRIBUTE=groups：指定用户组信息在 claims 中的属性名，Homarr 据此解析用户所属组。
AUTH_LOGOUT_REDIRECT_URL：登出后重定向到 Authelia 的登出端点，实现"登出 Homarr 即登出 Authelia"的完整单点登出体验。

配置逃生舱（Escape Hatch）

如前文所述，由于 Homarr 存在 Claims Hydration 缺陷，必须额外追加一个环境变量（对应官方 shortcode oidc-escape-hatch-claims-hydration.html 中example="disable"分支的说明）：

AUTH_OIDC_FORCE_USERINFO=true

注意：AUTH_OIDC_FORCE_USERINFO=true是本集成能否正常工作的关键——若缺失，Homarr 无法正确获取用户 claims，登录可能失败或无法识别用户身份。

Docker Compose 部署示例

若通过 Docker Compose 运行 Homarr，可将上述变量写入服务环境：

services: homarr: image: ghcr.io/homarr-labs/homarr:latest environment: AUTH_PROVIDERS: 'oidc' AUTH_OIDC_ISSUER: 'https://auth.example.com' AUTH_OIDC_CLIENT_ID: 'homarr' AUTH_OIDC_CLIENT_SECRET: 'insecure_secret' AUTH_OIDC_CLIENT_NAME: 'Authelia' AUTH_OIDC_SCOPE_OVERWRITE: 'openid email profile groups' AUTH_OIDC_GROUPS_ATTRIBUTE: 'groups' AUTH_LOGOUT_REDIRECT_URL: 'https://auth.example.com/logout' AUTH_OIDC_FORCE_USERINFO: 'true'

提示：上例补充了AUTH_OIDC_FORCE_USERINFO: 'true'，这是原文档标准 Compose 片段之外、基于 Claims Hydration 缺陷推导出的必要补充项，正式部署请务必带上。

用户组与权限映射

Homarr 侧的组权限分配不在 Authelia 范围内。用户在 Homarr 中被分配到哪个组、具备哪些权限，需要参考 Homarr 官方 SSO 文档中关于其 permission system 的说明进行配置。Authelia 侧的职责仅是：在groupsscope 被请求且AUTH_OIDC_GROUPS_ATTRIBUTE=groups已设置的情况下，把用户所属组作为groupsclaim 返回给 Homarr。

组信息来源于 Authelia 的认证后端（如文件用户数据库或 LDAP）中用户所属的用户组，这一数据链路由 Authelia 的 OIDC Provider 在授权时统一组装，详见 OpenID Connect 1.0 Claims 指南中对标准 claims 与自定义 claims 的说明。

从源码理解配置行为的底层机制

claims 的隐私化设计：Authelia 默认只在 ID Token 中放入最小化的授权证明 claims，其余 scope 授权的 claims 一律通过 UserInfo 端点由 Access Token 换取。这正是 Homarr 这类"不按规范去 UserInfo 拉取 claims"的客户端会出问题的根源，也是AUTH_OIDC_FORCE_USERINFO=true存在的意义（见 openid-connect-1.0-claims.md）。
known bugs 的模板化声明：文档中"Known Bugs / Claims Hydration"段落由 oidc-common.html 模板渲染，{{% oidc-common bugs="claims-hydration" %}}这一 shortcode 调用是官方在多个客户端集成文档中统一标注第三方应用兼容性问题的机制。
escape hatch 的文档化约定：{{% oidc-escape-hatch-claims-hydration example="disable" %}}在 oidc-escape-hatch-claims-hydration.html 中渲染时，因example="disable"参数而只输出告警提示、不输出默认的 claims_policies YAML 示例——这意味着 Homarr 场景下无需在 Authelia 侧配置claims_policies，只需 Homarr 侧的AUTH_OIDC_FORCE_USERINFO=true。

验证与排障建议

验证回调路径：确认 Homarr 的redirect_uris中的/api/auth/callback/oidc与实际回调地址一致；Homarr 侧 OIDC 登录按钮触发后若立即报错，优先检查该字段。
确认 issuer 无尾部斜杠：AUTH_OIDC_ISSUER末尾多余的/会导致发现端点（.well-known/openid-configuration）拼接异常。
检查 scope 一致性：Authelia 注册的scopes与 Homarr 的AUTH_OIDC_SCOPE_OVERWRITE应保持对应，否则部分属性（尤其groups）无法返回。
观察登录失败日志：若登录失败且提示无法获取用户信息，请确认AUTH_OIDC_FORCE_USERINFO=true已生效。
凭据匹配：Homarr 侧使用明文insecure_secret，Authelia 侧可存其 PBKDF2-SHA512 哈希，两者对应同一 secret 即可正常认证。

企业官网建设流程全解析