Authelia 集成 Ghostfolio:OpenID Connect 1.0 单点登录接入实战

Authelia 集成 Ghostfolio:OpenID Connect 1.0 单点登录接入实战 Authelia 集成 GhostfolioOpenID 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/autheliaGhostfolio 是一款开源的个人投资组合管理工具本指南演示如何将 Ghostfolio 接入 Authelia 内置的 OpenID Connect 1.0 Provider使访问者可以通过 Authelia 完成集中式身份认证SSO。本文以 Authelia v4.39.24 与 Ghostfolio v2.222.0 的组合为例完整覆盖 Authelia 侧客户端注册、Ghostfolio 侧环境变量配置、客户端凭据的安全生成与哈希存储并逐项解析每个配置参数在源码与文档层面的实际含义读完即可独立完成一次可运行的集成。本文对应的原始集成文档位于 docs/content/integration/openid-connect/clients/ghostfolio/index.md属于 Authelia 社区community支持级别的第三方应用集成指南可结合 OpenID Connect 1.0 集成总览 与 OpenID Connect 1.0 客户端配置 一起阅读。测试版本与支持级别官方集成文档记录了本次集成验证所使用的版本组合组件版本Autheliav4.39.24Ghostfoliov2.222.0该集成的支持级别为community社区即由社区维护并验证。在复现本指南时建议尽量使用不低于上述版本的 Authelia因为 OpenID Connect 1.0 客户端注册相关的配置项如token_endpoint_auth_method、require_pkce、pkce_challenge_method等在不同版本间存在差异。集成前需要明确的假设参数在动手配置前集成文档给出了以下四个假设值。它们决定了双方配置中大量 URL 与标识符的取值任何一处修改都需要同步到另一侧假设项取值说明Application Root URLhttps://ghostfolio.example.com/Ghostfolio 应用的根地址直接决定回调地址Authelia Root URLhttps://auth.example.com/Authelia 门户的根地址作为 OIDC 的 issuerClient IDghostfolio在 Authelia 注册的客户端标识必须与 Ghostfolio 侧一致Client Secretinsecure_secret演示用客户端密钥生产环境严禁使用其中最关键的联动关系是回调地址Redirect URIGhostfolio 的 OIDC 回调固定为https://ghostfolio.example.com/api/auth/oidc/callback它由 Application Root URL 推导而来。也就是说如果你把 Ghostfolio 部署在https://pf.example.com那么回调地址就必须相应改为https://pf.example.com/api/auth/oidc/callback同时 Authelia 客户端配置里的redirect_uris也必须同步更新。回调地址的匹配在 Authelia 中是严格、区分大小写的未在redirect_uris中登记的回调会被直接拒绝并产生错误见 redirect_uris 配置说明。文档中example.com、auth.example.com等占位符在 Authelia 官方站点上可通过站点变量sitevar自动替换为读者自己的域名本仓库内的 Markdown 源码中它们以{{ sitevar ... }}短代码形式存在。第一步在 Authelia 中注册 Ghostfolio 客户端以下 YAML 片段是集成文档给出的 Authelia客户端配置示例需要放置在你的configuration.yml的identity_providers.oidc.clients列表中。注意该示例只包含客户端注册部分Provider 级别的必填配置hmac_secret、jwks等仍需按照 OpenID Connect 1.0 Provider 配置 另行补齐完整的可参考骨架在仓库根目录的 config.template.yml 中有注释说明。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: ghostfolio client_name: Ghostfolio 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://ghostfolio.example.com/api/auth/oidc/callback scopes: - openid 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必填客户端的唯一标识必须与 Ghostfolio 侧配置的OIDC_CLIENT_ID完全一致。Authelia 对其有明确约束长度不得超过 100 字符、只能包含 RFC3986 无保留字符、且在所有已注册客户端中必须唯一。文档中的ghostfolio仅为便于阅读的演示值。client_name可选默认同client_id显示在 Authelia 授权/同意界面上的友好名称这里设置为Ghostfolio。client_secret条件必填Authelia 与 Ghostfolio 共享的密钥。示例中存储的是明文insecure_secret的PBKDF2-SHA512 摘要$pbkdf2-sha512$310000$...而非明文本身——这是官方强烈推荐的做法。注意Ghostfolio 侧配置的必须是明文只有 Authelia 的配置文件里存哈希。public: false声明这是一个机密客户端confidential client。机密客户端能够安全保存凭据因此必须配置client_secret若为true公开客户端如 SPA则client_secret必须留空。依据见 RFC6749 Section 2.1 的客户端类型定义。authorization_policy: two_factor该客户端执行授权请求前要求用户完成两级认证。可取值有one_factor、two_factor或引用 Provider 级authorization_policies中自定义的策略名。需要注意这个策略仅作用于授权请求与 Authelia 的访问控制规则Access Control Rules是两套独立机制不要混为一谈。require_pkce: false与pkce_challenge_method: 不强制要求 PKCE也不绑定具体的 challenge 方法。pkce_challenge_method的有效值为空字符串、plain或S256后者是强烈推荐的。若设置了一个非空值会同时隐式启用require_pkce。由于 Ghostfolio 的 OIDC 实现较简单集成文档按最保守方式关闭了 PKCE 强制。redirect_uris允许的回调地址白名单即上文推导出的https://ghostfolio.example.com/api/auth/oidc/callback。URI 区分大小写且 scheme 必须是http或https。scopes: [openid]允许该客户端请求的授权范围。Authelia 预定义的范围为openid、groups、profile、email默认全部授予openid是 OpenID Connect 协议必需的最小范围。若配置了未定义的自定义 scopeAuthelia 会在日志中输出警告。范围与声明的详细定义见 scope definitions。response_types: [code]仅允许授权码Authorization Code响应类型。官方在文档中明确提示除code以外的响应类型安全性较差只使用code是推荐做法。grant_types: [authorization_code]允许该客户端使用的授权类型与response_types: [code]配套走标准的 Authorization Code Flow。access_token_signed_response_alg: none与userinfo_signed_response_alg: none访问令牌与 UserInfo 响应均不进行 JWT 签名编码保持默认的不透明opaque访问令牌与普通 JSON UserInfo 响应格式。这是大多数应用所期望的行为只有需要资源服务器做无状态校验RFC9068 JWT Profile Access Token的重度场景才需要改为签名算法。token_endpoint_auth_method: client_secret_post客户端在令牌端点以client_secret_post方式提交凭据即把client_id与client_secret作为表单参数 POST 到令牌端点。支持的取值还包括client_secret_basic默认值、client_secret_jwt、private_key_jwt和none。Ghostfolio 采用的是client_secret_post因此必须显式配置该项否则 Authelia 默认按client_secret_basic期望凭据会导致令牌换取失败。第二步在 Ghostfolio 侧启用 OIDC 认证Ghostfolio 的配置方式只有一种环境变量。共涉及三个必填变量环境变量取值示例作用ENABLE_FEATURE_AUTH_OIDCtrue启用 Ghostfolio 的 OIDC 登录功能开关OIDC_ISSUERhttps://auth.example.comAuthelia 的 OIDC 颁发者地址即 Authelia Root URL注意末尾不带斜杠OIDC_CLIENT_IDghostfolio必须与 Authelia 中注册的client_id完全一致OIDC_CLIENT_SECRETinsecure_secret必须为明文密钥与 Authelia 中client_secret哈希所对应的原文一致方式一.env 文件Bare-Metal / Node 部署ENABLE_FEATURE_AUTH_OIDCtrue OIDC_ISSUERhttps://auth.example.com OIDC_CLIENT_IDghostfolio OIDC_CLIENT_SECRETinsecure_secret方式二Docker Composeservices: ghostfolio: environment: ENABLE_FEATURE_AUTH_OIDC: true OIDC_ISSUER: https://auth.example.com OIDC_CLIENT_ID: ghostfolio OIDC_CLIENT_SECRET: insecure_secret配置完成后Ghostfolio 会把用户引导到 Authelia 完成登录并通过/api/auth/oidc/callback接收授权码换取令牌。这里有一个常见的集成陷阱需要提醒OIDC_ISSUER必须与 Authelia 实际对外暴露的 issuer 精确一致包括协议与端口否则 Ghostfolio 在拉取发现文档Discovery时会因为 issuer 不匹配而拒绝工作——Authelia 的 FAQ 中专门解释了发现端点返回错误 issuer 时的排查思路。客户端凭据安全生成随机 ID / Secret 并以哈希存储集成指南oidc-common 公共段落对所有第三方应用集成给出了统一的安全要求Ghostfolio 集成同样适用每个客户端应使用唯一且随机生成的 ID 与 Secret 对ID 与 Secret 长度建议超过 40 字符官方示例建议 64~72 字符ID 与 Secret只能包含 RFC3986 无保留字符A-Z a-z 0-9 - . _ ~。因为部分客户端含以client_secret_post认证的应用在向令牌端点发送凭据时不会正确做 URL 编码含特殊字符会导致凭据明明正确却报错Authelia 配置文件中的client_secret应存储为受支持的哈希格式推荐 PBKDF2而 Ghostfolio 侧则配置对应的明文。Authelia 提供了现成的命令来同时完成生成随机值与生成哈希两步# 生成 72 字符的随机 Client IDRFC3986 字符集避免编码问题 authelia crypto rand --length 72 --charset rfc3986 # 生成随机 Client Secret 并直接输出其 PBKDF2 哈希用于写入 Authelia 配置 authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986使用 Docker 时只需在前面加上docker run --rm authelia/authelia:latest前缀即可获得相同行为。上述命令的完整说明见 FAQ如何生成客户端标识符或客户端密钥 以及 生成安全值参考指南。需要注意work factor工作因子的取舍client_secret以哈希形式存储时Authelia 每次在令牌端点认证客户端都要执行一次哈希运算而 PBKDF2 的迭代次数示例中的310000直接决定耗时。如果客户端操作出现超时可适当降低迭代次数可用time authelia crypto hash generate pbkdf2 --variant sha512 --iterations 310000 --password insecure_password这类命令实测当前硬件的耗时。相关讨论同样收录在 FAQ 的工作因子调优章节。另外需要特别强调client_secret以明文写入 Authelia 配置属于已弃用行为未来版本不保证继续支持务必迁移到哈希存储。登录流程回顾与配置核对清单完成上述两步配置后一次完整的 SSO 登录流程如下用户访问 Ghostfolio 并点击 OIDC 登录Ghostfolio 将用户重定向到 Authelia 的授权端点Authelia 要求用户完成认证本示例为two_factor即密码 第二因素并视配置向用户展示同意页面认证通过后Authelia 将授权码通过redirect_uri/api/auth/oidc/callback送回 GhostfolioGhostfolio 以client_secret_post方式携带凭据访问 Authelia 令牌端点换取 ID Token / Access TokenGhostfolio 校验令牌后完成本地会话建立。最后对照以下清单做一次自检可以覆盖绝大多数配置错误Authelia 的redirect_uris与 Ghostfolio 实际回调地址/api/auth/oidc/callback完全一致且大小写正确client_id两侧一致且只含 RFC3986 无保留字符、不超过 100 字符Ghostfolio 的OIDC_CLIENT_SECRET是明文Authelia 的client_secret是对应哈希token_endpoint_auth_method显式配置为client_secret_post否则默认按client_secret_basic处理OIDC_ISSUER与 Authelia 实际 issuer 精确一致协议、主机、端口均无差异identity_providers.oidc下的 Provider 级必填项hmac_secret、jwks等已按 Provider 配置文档 补齐。如果集成过程中遇到凭据正确却认证失败的问题多半与客户端对凭据的 URL 编码处理有关可参考 FAQ 对应条目 做进一步排查。更多 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),仅供参考