Authelia 集成 Actual BudgetOpenID 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 官方集成文档为骨架完整讲解如何将Actual Budget开源个人理财应用接入 Authelia 的 OpenID Connect 1.0 Provider实现统一身份认证与单点登录SSO。读完本文你将掌握 Authelia 侧客户端Registered Client的完整 YAML 配置、Actual Budget 侧三种可选的配置方式配置文件、环境变量、Web GUI以及 Client ID / Client Secret 的生成与哈希存储等安全细节可直接复制配置落地到自己的环境中。前置阅读与适用版本在开始配置前建议先阅读 Authelia 的 OpenID Connect 1.0 集成介绍 与 OpenID Connect 1.0 客户端配置指南理解 Relying Party依赖方即 Actual Budget与 Authorization Server授权服务器即 Authelia之间的角色关系。本文档示例经过以下版本组合的验证Autheliav4.38.18Actual Budgetv25.1.0重要阅读提示在配置任何 OpenID Connect 1.0 注册客户端之前请仔细阅读本文涉及的关键约定Client ID 唯一性、Client Secret 存储方式、重定向 URI 匹配规则等这些约定直接关系到集成能否成功以及安全性是否达标。配置前提假设本文示例基于以下假设你可以根据实际环境替换相应值配置项示例值说明Application Root URLhttps://actual-budget.example.com/决定回调 URI 的形态Authelia Root URLhttps://auth.example.com/Authelia 实例地址即 OIDC IssuerClient IDactual-budgetAuthelia 侧注册的客户端标识Client Secretinsecure_secret演示用明文密钥生产环境严禁使用关键约束Application Root URL 决定了 Actual Budget 的回调 URI其格式为https://actual-budget.example.com/login。如果你修改了该值必须在 Authelia 侧同步更新redirect_uris否则授权回调会被 Authelia 判定为不安全 URI 而拒绝。Authelia 侧注册 OpenID Connect 客户端在 Authelia 的configuration.yml中于identity_providers.oidc.clients下注册 Actual Budget 客户端。OIDC Provider 的其他必需配置部分如 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: actual-budget client_name: Actual Budget 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://actual-budget.example.com/openid/callback 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 配置参考上述配置中每个选项的含义与约束如下client_id客户端唯一标识必须与 Actual Budget 侧配置的 Client ID 完全一致。合法取值要求长度不超过 100 字符、只包含 RFC3986 Unreserved Characters 相关校验器中会对上述约束逐一校验。client_name客户端在 Authelia 用户界面中展示的友好名称默认与client_id相同这里显式设置为Actual Budget。client_secretAuthelia 与 Actual Budget 共享的密钥。示例中存放的是明文insecure_secret的 PBKDF2-SHA512 哈希摘要$pbkdf2-sha512$310000$...而非明文本身——这是官方强烈推荐的存储方式。需注意Actual Budget 侧配置的仍是明文密钥哈希值仅用于 Authelia 配置文件。public: false声明为机密客户端Confidential Client Type见 RFC6749 Section 2.1。这类客户端能够安全保管凭证因此必须提供client_secret并在 Token 端点进行客户端认证。authorization_policy: two_factor该客户端的授权策略即用户在授权请求时必须达到的认证强度取值为one_factor、two_factor或 Provider 中authorization_policies自定义的策略名。此选项仅作用于 OIDC 授权请求与 访问控制规则 是两套独立机制不应混淆。require_pkce: false与pkce_challenge_method: 本示例未强制要求 PKCE。若需要强制可将require_pkce设为truepkce_challenge_method的合法值为空字符串、plain或S256其中S256被强烈推荐且设置该值会等效启用require_pkce。redirect_urisActual Budget 合法回调 URI 列表。示例为https://actual-budget.example.com/openid/callback。所有不在列表中的回调都会被判定为不安全URI 区分大小写且 scheme 必须是http或https。注意此回调路径与前面假设中提到的/login回调并不相同配置时务必以 Actual Budget 实际使用的回调路径为准。scopes允许该客户端消费的 scope 列表默认值为openid,groups,profile,email。各 scope 的具体含义与返回的 Claims 参见 OpenID Connect 1.0 Claims 与 Scope 定义openid启用 OpenID Connect 1.0 语义返回 ID Tokenprofile返回用户资料信息name、preferred_username、locale等groups在 ID Token 的 Claims 中包含用户所属组groups数组email返回邮箱信息email、email_verified、alt_emails。response_types: [code]仅使用授权码流程Authorization Code Flow。官方安全提示建议只使用code其他响应类型如id_token、token等隐式/混合流程安全性较弱。grant_types: [authorization_code]允许的授权类型。若后续需要刷新令牌应追加refresh_token并配合offline_accessscope 使用。access_token_signed_response_alg: none与userinfo_signed_response_alg: none访问令牌与 UserInfo 响应不进行 JWT 签名以纯 JSON/不透明令牌形式返回none表示不签名。这符合多数 Web 应用客户端的默认预期。token_endpoint_auth_method: client_secret_basic客户端在 Token 端点使用 HTTP Basic 认证方式提交 Client ID 与 Secret。这是机密客户端类型的规范默认值其他可选值包括client_secret_post、client_secret_jwt、private_key_jwt与none。生成安全的 Client ID 与 Client Secret示例中的actual-budget与insecure_secret仅用于演示生产环境必须替换。Authelia 官方 FAQHow do I generate a client identifier or client secret?建议每个客户端使用独立的随机凭证对长度超过 40 字符且只包含 RFC3986 非保留字符。使用 Authelia 内置命令可以一步生成符合规范的凭证# 生成 72 字符的随机 Client ID authelia crypto rand --length 72 --charset rfc3986 # 生成 72 字符随机 Client Secret并同时输出 PBKDF2-SHA512 哈希存 Authelia 配置用与明文存 Actual Budget 用 authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986Docker 部署环境下将authelia命令替换为docker run --rm authelia/authelia:latest authelia ...即可。Actual Budget 侧配置 OpenID ConnectActual Budget 提供三种配置方式任选其一即可。方式一配置文件在 Actual Budget 的配置文件中加入如下 JSON 片段{ openId: { discoveryURL: https://auth.example.com, client_id: actual-budget, client_secret: insecure_secret, server_hostname: https://actual-budget.example.com, authMethod: oauth2 } }discoveryURLAuthelia 的 OIDC Discovery 端点地址。Actual Budget 会自动在其后追加/.well-known/openid-configuration获取 Provider 元数据client_id/client_secret与 Authelia 侧注册值保持一致此处为明文密钥server_hostnameActual Budget 自身的对外根地址用于构造回调 URIauthMethod固定为oauth2表示使用 OAuth 2.0 / OIDC 授权流程。方式二环境变量同样支持通过环境变量完成配置适合容器化部署。标准环境变量.envACTUAL_OPENID_DISCOVERY_URLhttps://auth.example.com ACTUAL_OPENID_CLIENT_IDactual-budget ACTUAL_OPENID_CLIENT_SECRETinsecure_secret ACTUAL_OPENID_SERVER_HOSTNAMEhttps://actual-budget.example.com ACTUAL_OPENID_AUTH_METHODoauth2Docker Compose 写法services: actual-budget: environment: ACTUAL_OPENID_DISCOVERY_URL: https://auth.example.com/.well-known/openid-configuration ACTUAL_OPENID_CLIENT_ID: actual-budget ACTUAL_OPENID_CLIENT_SECRET: insecure_secret ACTUAL_OPENID_SERVER_HOSTNAME: https://actual-budget.example.com ACTUAL_OPENID_AUTH_METHOD: oauth2注意标准.env写法中ACTUAL_OPENID_DISCOVERY_URL只填 Provider 根地址而 Docker Compose 示例中显式追加了/.well-known/openid-configuration路径。两种写法对应 Actual Budget 不同版本/部署方式对 Discovery URL 的解析差异请以你的 Actual Budget 版本实际支持的形式为准若无法确定可优先采用根地址形式由客户端自动补全 well-known 路径。方式三Web GUI无需编辑任何文件通过 Actual Budget 的图形界面即可完成配置打开任意 Budget 文件进入Settings点击Start Using OpenID配置以下选项OpenID ProviderOtherOpenID Provider URLhttps://auth.example.comClient IDactual-budgetClient Secretinsecure_secret点击OK保存。集成验证与常见问题排查配置完成后可通过以下要点验证集成是否成功Discovery 端点可达在浏览器访问https://auth.example.com/.well-known/openid-configuration应返回包含authorization_endpoint、token_endpoint、jwks_uri等字段的 JSON 元数据端点清单可参考 OpenID Connect 1.0 集成介绍 的 Endpoint Implementations 章节。Actual Budget 依赖该元数据完成协议握手若不可达将直接导致登录失败。回调 URI 精确匹配Authelia 的redirect_uris必须与 Actual Budget 实际发起的回调地址逐字符一致区分大小写。常见问题是 URL 末尾缺少/多出斜杠、或端口号不一致导致授权被拒。凭证一致性Authelia 注册的client_secret哈希所对应的明文必须与 Actual Budget 侧填写的明文完全一致。若使用client_secret_basic认证方式Client ID 与 Secret 中应避免特殊字符RFC3986 非保留字符之外的值防止部分客户端在 URL 编码环节出错——这也是官方 FAQ 中反复强调的已知兼容性问题。认证强度符合预期authorization_policy: two_factor意味着用户登录 Actual Budget 时将被要求完成两步认证如 TOTP、WebAuthn 等适用于需要更高安全边界的自托管财务类应用如需降级为仅密码认证可改为one_factor。参考文档OpenID Connect 1.0 集成介绍协议实现细节、端点清单、安全机制PKCE、PAR、JARM 等说明。OpenID Connect 1.0 客户端配置客户端注册的全部配置项与默认值。OpenID Connect 1.0 Claims 与 Scope 定义各 scope 对应返回的 Claims 明细表。OpenID Connect 1.0 常见问题Client ID/Secret 生成、明文存储弃用说明、工作因子调优等。Actual Budget 官方文档《Authenticating With an OpenID Provider》见 actualbudget.org/docs/config/oauth-auth其中说明了 Actual Budget 对 OpenID Connect 的具体实现细节。【免费下载链接】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），仅供参考