Authelia OpenID Connect 1.0 集成 Dashy：SSO 单点登录配置完整指南-编程实验室

Authelia OpenID Connect 1.0 集成 Dashy：SSO 单点登录配置完整指南

【免费下载链接】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 的 OpenID Connect 1.0 Provider 中注册 Dashy 客户端，并完成 Dashy 侧的 OIDC 配置，实现通过 Authelia 统一认证门户为 Dashy 仪表盘提供单点登录与双因素认证能力。文中将完整覆盖 Authelia 客户端配置、Dashy 应用配置、PKCE 与公共客户端（public client）机制、以及针对 Dashy 已知缺陷的 Claims 逃生舱（Escape Hatch）配置，读完即可落地一套可运行的集成方案。

测试版本

本集成指南对应的测试版本如下，配置示例均基于这些版本验证：

组件	版本
Authelia	v4.39.24
Dashy	v3.1.1

该集成以社区（community）级别提供支持，Dashy 客户端存在已知的显著缺陷（详见下文"配置逃生舱"章节），集成时需按本指南的适配方案处理。

前置假设

本示例基于以下约定进行说明，你可以按实际环境替换对应值：

应用根地址（Application Root URL）：https://dashy.example.com/
Authelia 根地址（Authelia Root URL）：https://auth.example.com/
客户端 ID（Client ID）：dashy

本文中部分占位值（如example.com域名）在官方文档站点中可通过文档变量自动替换，此处按默认值example.com展开说明。

集成原理概览

Dashy 是典型的浏览器端单页应用（SPA），无法安全保管客户端密钥，因此必须按public（公共）客户端类型注册，并通过PKCE（Proof Key for Code Exchange）与授权码流程（Authorization Code Flow）完成认证：

用户访问 Dashy，Dashy 将浏览器重定向到 Authelia 的授权端点；
用户在 Authelia 门户完成认证（根据authorization_policy可能要求双因素认证），并授权 Dashy 请求的 scopes；
Authelia 将授权码回传给 Dashy 的redirect_uri；
Dashy 携带 PKCEcode_verifier向 Authelia 令牌端点换取 ID Token 与 Access Token。

Dashy 侧只需配置 Authelia 的根地址，Dashy 会通过 OpenID Connect Discovery 机制自动发现 Authelia 暴露的元数据端点（即https://auth.example.com/.well-known/openid-configuration），无需逐一手写各端点路径。Authelia 支持的端点清单见 OpenID Connect 1.0 集成指南的"Endpoint Implementations"章节。

第一步：在 Authelia 中注册 Dashy 客户端

在 Authelia 的configuration.yml中，identity_providers.oidc.clients下新增如下客户端配置。identity_providers.oidc的其他必填部分（如 issuer、密钥等）需按 OpenID Connect 1.0 Provider 配置另行配置：

identity_providers: oidc: ## The other portions of the mandatory OpenID Connect 1.0 configuration go here. ## See: https://www.authelia.com/c/oidc clients: - client_id: 'dashy' client_name: 'Dashy' public: true authorization_policy: 'two_factor' require_pkce: true pkce_challenge_method: 'S256' redirect_uris: - 'https://dashy.example.com' scopes: - 'openid' - 'profile' - 'email' - 'groups' - 'roles' grant_types: - 'authorization_code' response_types: - 'code' access_token_signed_response_alg: 'none' userinfo_signed_response_alg: 'none' token_endpoint_auth_method: 'none'

各配置项的作用与依据

以下逐项说明上述配置的含义，完整选项说明见 OpenID Connect 1.0 客户端配置参考：

配置项	取值	说明
`client_id`	`dashy`	客户端唯一标识，必须与应用侧配置完全一致。按客户端配置参考的约束：不超过 100 字符、仅含 RFC3986 无保留字符（Unreserved Characters）、且与其他客户端全局唯一。指南中的取值仅为演示用途，生产环境建议使用随机长字符串（参考 FAQ 中客户端标识生成方法）
`client_name`	`Dashy`	展示在 Authelia 授权界面上的友好名称，默认与`client_id`相同
`public`	`true`	启用公共客户端类型（RFC6749 Section 2.1 定义的 Client Types），适用于无法安全保管凭据的 SPA / CLI 应用。启用后必须将`client_secret`留空
`authorization_policy`	`two_factor`	该客户端的授权策略，取值可为`one_factor`、`two_factor`或 Provider 层`authorization_policies`中自定义的策略名。注意它仅作用于授权请求，与访问控制规则（Access Control Rules）是两套机制
`require_pkce`	`true`	强制该客户端使用 PKCE。作为公共客户端，这是抵御授权码拦截攻击的关键手段
`pkce_challenge_method`	`S256`	强制指定 PKCE 挑战方法。合法值为空、`plain`、`S256`；官方强烈推荐`S256`（对`code_verifier`做 SHA-256 摘要后 Base64URL 编码，而非明文传输）。配置该项会同时等效启用`require_pkce`
`redirect_uris`	`https://dashy.example.com`	合法的回调 URI 列表，大小写敏感，必须包含`http`或`https`scheme，且与 Dashy 实际回调地址精确匹配（注意示例中该 URI 没有路径与结尾斜杠，需与 Dashy 端保持一致），否则授权请求会被拒绝
`scopes`	`openid`、`profile`、`email`、`groups`、`roles`	允许该客户端申请的 scopes。`openid`是启用 OIDC 语义（返回 ID Token 等）的必要 scope；`profile`、`email`、`groups`的定义见 OpenID Connect 1.0 Claims 指南的 Scope Definitions。`roles`为 Dashy 自身请求的 scope——按客户端配置参考的说明，配置了未在 Authelia scope 定义中的取值时，日志中会出现告警，属预期现象
`grant_types`	`authorization_code`	允许的授权类型。官方默认即`authorization_code`，且强烈建议不要随意更改
`response_types`	`code`	响应类型。仅`code`（授权码）是最安全的选择，其他响应类型（如 implicit）安全性较差，不建议使用
`access_token_signed_response_alg`	`none`	Access Token 签名算法，默认即为`none`（不签名、不编码为 JWT）。只有配置非`none`值才会按 RFC9068 将 Access Token 编码为 JWT，Dashy 不依赖此能力
`userinfo_signed_response_alg`	`none`	UserInfo 端点响应的签名算法，默认`none`，此时 UserInfo 返回普通 JSON（`application/json`），Dashy 可正常解析
`token_endpoint_auth_method`	`none`	令牌端点客户端认证方式。公共客户端类型按规范默认即为`none`（无需认证），而机密客户端默认是`client_secret_basic`

第二步：配置 Dashy 应用

Dashy 侧仅支持通过配置文件（Configuration File）方式启用 OIDC。在 Dashy 的配置文件（appConfig部分）中加入以下内容：

appConfig: auth: enableOidc: true oidc: clientId: 'dashy' endpoint: 'https://auth.example.com'

参数说明：

enableOidc：设为true以启用 Dashy 的 OIDC 登录；
clientId：必须与 Authelia 侧注册的client_id（即dashy）完全一致；
endpoint：Authelia 的根地址。Dashy 会基于该地址访问 OIDC Discovery 元数据（/.well-known/openid-configuration）自动发现授权端点、令牌端点、UserInfo 端点等，因此只需填写根地址即可。

配置完成后，访问 Dashy 时即会跳转至 Authelia 完成登录，并在 Authelia 侧完成授权后回调 Dashy。

配置逃生舱：处理 Dashy 的 Claims Hydration 缺陷

以下内容对应 oidc-common.html 中记录的 "Known Bugs / Claims Hydration" 及 oidc-escape-hatch-claims-hydration.html 短代码生成的内容。

已知缺陷说明

Dashy 客户端并未真正支持 OpenID Connect 1.0：它没有遵循规范要求的流程来获取它所需的 claims。按 OpenID Connect Core 1.0 Section 5.4 的要求，客户端应当假设通过 scope 请求的 claims 可以使用 Access Token 在UserInfo 端点获取；Dashy 不执行这一流程，因此无法通过常规方式拿到email、preferred_username等 claims。

同时，这类缺陷通常还意味着客户端忽略了规范的 claims 稳定性要求（Claim Stability）——规范严格要求客户端只能通过sub与issclaims 锚定账户，这两点都是客户端未正确支持 OIDC 的明显标志。

逃生舱配置

Authelia 为此提供了逃生舱机制：通过 Provider 层的claims_policies将本应通过 UserInfo 端点返回的 claims额外水合（hydrate）进 ID Token，从而绕过 Dashy 不调用 UserInfo 的缺陷。上述 Dashy 配置需要追加以下内容：

identity_providers: oidc: claims_policies: dashy: id_token: ['email', 'email_verified', 'alt_emails', 'preferred_username', 'name'] clients: - client_id: 'dashy' claims_policy: 'dashy'

要点：

claims_policies下的键名（此处为dashy）是任意值，通过客户端配置项的claims_policy字段引用，详见 Provider 配置的 claims_policies；
id_token列表中的 claims 会在对应 scope 被授予的前提下，自动复制到 ID Token 中；
若未配置逃生舱，可预期 Dashy 在获取email、preferred_username、name等用户信息时失败。

安全注意事项

按 Provider 配置参考中的安全提示，claims_policies.id_token属于不应常规使用的逃生舱：它会把通常不加密的、可识别个人身份的敏感信息（PII）写入 ID Token。该行为仅在客户端确实不支持 OIDC 时才有必要，并且是客户端存在显著 bug 的表现；同时它也常常意味着客户端没有使用iss/sub锚定用户，这本身是一个较为严重的安全问题。因此该选项强烈不建议用于正常客户端，官方建议推动 Dashy 上游修复此缺陷，逃生舱仅按"尽力而为"（best effort）原则提供。

常见问题与安全建议

client_id的生成：指南中的dashy仅用于演示。生产环境应使用随机的、长度足够的字符串（官方建议 64 个随机字符），并确保只包含 RFC3986 无保留字符、不超过 100 字符且全局唯一。生成方法见 FAQ：如何生成客户端标识或密钥。
公共客户端必须启用 PKCE：Dashy 无法保密保存client_secret，因此以public: true注册并配合S256挑战方法。这能保证即使公共客户端无法在令牌端点进行认证，兑换授权码的一方也必须证明其持有绑定到该授权码的code_verifier，从而缓解授权码拦截攻击。
回调地址必须精确匹配：redirect_uris是大小写敏感且逐字符精确匹配的，Dashy 与 Authelia 两侧的地址（包括是否带路径、结尾斜杠）必须完全一致，否则授权会直接报错。
用户身份锚定：根据 Claims 指南的说明，iss与sub的组合是规范保证唯一的、用于将账户关联到 Authelia 的可靠方式；email、preferred_username等 claims 只应被用于新账户的预置（provisioning），不应作为账户锚定依据。

验证与排查

通过浏览器访问 Authelia 的 Discovery 端点https://auth.example.com/.well-known/openid-configuration，确认授权端点、令牌端点、UserInfo 端点等元数据可正常返回，这是 Dashy 自动发现端点的前提；
触发 Dashy 登录并观察是否成功跳转至 Authelia 认证页；认证后若 Dashy 无法显示用户信息（如邮箱、用户名），优先检查是否已按上文配置claims_policies逃生舱；
若 Dashy 侧报回调错误，核对redirect_uris与 Dashy 实际回调地址是否逐字符一致；
若怀疑 scope 配置问题，可查阅 Authelia 日志中关于未定义 scope 的告警信息。