Authelia OpenID Connect 1.0 集成 DashySSO 单点登录配置完整指南【免费下载链接】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配置读完即可落地一套可运行的集成方案。测试版本本集成指南对应的测试版本如下配置示例均基于这些版本验证组件版本Autheliav4.39.24Dashyv3.1.1该集成以社区community级别提供支持Dashy 客户端存在已知的显著缺陷详见下文配置逃生舱章节集成时需按本指南的适配方案处理。前置假设本示例基于以下约定进行说明你可以按实际环境替换对应值应用根地址Application Root URLhttps://dashy.example.com/Authelia 根地址Authelia Root URLhttps://auth.example.com/客户端 IDClient IDdashy本文中部分占位值如example.com域名在官方文档站点中可通过文档变量自动替换此处按默认值example.com展开说明。集成原理概览Dashy 是典型的浏览器端单页应用SPA无法安全保管客户端密钥因此必须按public公共客户端类型注册并通过PKCEProof Key for Code Exchange与授权码流程Authorization Code Flow完成认证用户访问 DashyDashy 将浏览器重定向到 Authelia 的授权端点用户在 Authelia 门户完成认证根据authorization_policy可能要求双因素认证并授权 Dashy 请求的 scopesAuthelia 将授权码回传给 Dashy 的redirect_uriDashy 携带 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_iddashy客户端唯一标识必须与应用侧配置完全一致。按 客户端配置参考 的约束不超过 100 字符、仅含 RFC3986 无保留字符Unreserved Characters、且与其他客户端全局唯一。指南中的取值仅为演示用途生产环境建议使用随机长字符串参考 FAQ 中客户端标识生成方法client_nameDashy展示在 Authelia 授权界面上的友好名称默认与client_id相同publictrue启用公共客户端类型RFC6749 Section 2.1 定义的 Client Types适用于无法安全保管凭据的 SPA / CLI 应用。启用后必须将client_secret留空authorization_policytwo_factor该客户端的授权策略取值可为one_factor、two_factor或 Provider 层authorization_policies中自定义的策略名。注意它仅作用于授权请求与访问控制规则Access Control Rules是两套机制require_pkcetrue强制该客户端使用 PKCE。作为公共客户端这是抵御授权码拦截攻击的关键手段pkce_challenge_methodS256强制指定 PKCE 挑战方法。合法值为空、plain、S256官方强烈推荐S256对code_verifier做 SHA-256 摘要后 Base64URL 编码而非明文传输。配置该项会同时等效启用require_pkceredirect_urishttps://dashy.example.com合法的回调 URI 列表大小写敏感必须包含http或httpsscheme且与 Dashy 实际回调地址精确匹配注意示例中该 URI 没有路径与结尾斜杠需与 Dashy 端保持一致否则授权请求会被拒绝scopesopenid、profile、email、groups、roles允许该客户端申请的 scopes。openid是启用 OIDC 语义返回 ID Token 等的必要 scopeprofile、email、groups的定义见 OpenID Connect 1.0 Claims 指南的 Scope Definitions。roles为 Dashy 自身请求的 scope——按 客户端配置参考 的说明配置了未在 Authelia scope 定义中的取值时日志中会出现告警属预期现象grant_typesauthorization_code允许的授权类型。官方默认即authorization_code且强烈建议不要随意更改response_typescode响应类型。仅code授权码是最安全的选择其他响应类型如 implicit安全性较差不建议使用access_token_signed_response_algnoneAccess Token 签名算法默认即为none不签名、不编码为 JWT。只有配置非none值才会按 RFC9068 将 Access Token 编码为 JWTDashy 不依赖此能力userinfo_signed_response_algnoneUserInfo 端点响应的签名算法默认none此时 UserInfo 返回普通 JSONapplication/jsonDashy 可正常解析token_endpoint_auth_methodnone令牌端点客户端认证方式。公共客户端类型按规范默认即为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完全一致endpointAuthelia 的根地址。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_policiesid_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如何生成客户端标识或密钥。公共客户端必须启用 PKCEDashy 无法保密保存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 的告警信息。延伸阅读Dashy 集成文档原文OpenID Connect 1.0 集成指南含端点、响应类型、算法、安全机制OpenID Connect 1.0 客户端配置参考OpenID Connect 1.0 Provider 配置参考OpenID Connect 1.0 Claims 指南Scope 定义与 Claims 表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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考