企业官网建设流程全解析

Authelia 集成 Actual Budget：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

本篇技术指南以 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）之间的角色关系。

本文档示例经过以下版本组合的验证：

• Authelia：v4.38.18
• Actual Budget：v25.1.0

重要阅读提示：在配置任何 OpenID Connect 1.0 注册客户端之前，请仔细阅读本文涉及的关键约定（Client ID 唯一性、Client Secret 存储方式、重定向 URI 匹配规则等），这些约定直接关系到集成能否成功以及安全性是否达标。

配置前提假设

本文示例基于以下假设，你可以根据实际环境替换相应值：

关键约束：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_secret：Authelia 与 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设为true；pkce_challenge_method的合法值为空字符串、plain或S256，其中S256被强烈推荐，且设置该值会等效启用require_pkce。
• redirect_uris：Actual 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 Token；
  • profile：返回用户资料信息（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 官方 FAQ（How 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 rfc3986

Docker 部署环境下将authelia命令替换为docker run --rm authelia/authelia:latest authelia ...即可。

Actual Budget 侧：配置 OpenID Connect

Actual 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" } }

• discoveryURL：Authelia 的 OIDC Discovery 端点地址。Actual Budget 会自动在其后追加/.well-known/openid-configuration获取 Provider 元数据；
• client_id/client_secret：与 Authelia 侧注册值保持一致（此处为明文密钥）；
• server_hostname：Actual Budget 自身的对外根地址，用于构造回调 URI；
• authMethod：固定为oauth2，表示使用 OAuth 2.0 / OIDC 授权流程。

方式二：环境变量

同样支持通过环境变量完成配置，适合容器化部署。

标准环境变量（.env）：

ACTUAL_OPENID_DISCOVERY_URL=https://auth.example.com 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

Docker 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 的图形界面即可完成配置：

1. 打开任意 Budget 文件；
2. 进入Settings；
3. 点击Start Using OpenID；
4. 配置以下选项：
   • OpenID Provider：Other
   • OpenID Provider URL：https://auth.example.com
   • Client ID：actual-budget
   • Client Secret：insecure_secret
5. 点击OK保存。

集成验证与常见问题排查

配置完成后，可通过以下要点验证集成是否成功：

1. Discovery 端点可达：在浏览器访问https://auth.example.com/.well-known/openid-configuration，应返回包含authorization_endpoint、token_endpoint、jwks_uri等字段的 JSON 元数据（端点清单可参考 OpenID Connect 1.0 集成介绍 的 Endpoint Implementations 章节）。Actual Budget 依赖该元数据完成协议握手，若不可达将直接导致登录失败。
2. 回调 URI 精确匹配：Authelia 的redirect_uris必须与 Actual Budget 实际发起的回调地址逐字符一致（区分大小写）。常见问题是 URL 末尾缺少/多出斜杠、或端口号不一致导致授权被拒。
3. 凭证一致性：Authelia 注册的client_secret哈希所对应的明文，必须与 Actual Budget 侧填写的明文完全一致。若使用client_secret_basic认证方式，Client ID 与 Secret 中应避免特殊字符（RFC3986 非保留字符之外的值），防止部分客户端在 URL 编码环节出错——这也是官方 FAQ 中反复强调的已知兼容性问题。
4. 认证强度符合预期：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