Authelia 集成 ezBookkeeping：OpenID Connect 1.0 单点登录配置实战指南

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

导读

ezBookkeeping 是一款自托管的个人记账应用，支持通过 OpenID Connect 1.0 接入外部身份提供方。本文以 Authelia 作为 OpenID Connect 1.0 Provider（授权服务器），完整讲解如何在 Authelia 中注册 ezBookkeeping 客户端、如何通过配置文件 / 环境变量 / Docker Compose 三种方式完成 ezBookkeeping 侧的对接，并深入剖析 PKCE、授权码流程、Scope 与 Claim 绑定等底层原理，帮助你在一台服务器上以 Authelia 的统一登录门户（含双因素认证）保护 ezBookkeeping 的全部访问入口。读完本文你将能独立完成这套 SSO 集成，并具备定位常见配置错误的排查能力。

集成概览与测试版本

本文对应的集成方案在以下版本组合下经过官方验证：

该集成属于社区维护级别（文档 front matter 中support.level: community），但integration: true，即已被验证可正常工作。整体架构非常简单：ezBookkeeping 作为 OpenID Connect 1.0 的 Relying Party（依赖方），把用户登录重定向到 Authelia；Authelia 完成用户名/密码以及可选的双因素认证后，通过标准授权码流程把身份信息交还给 ezBookkeeping。

前置假设

为便于说明，本文示例使用以下占位值（实际部署时请替换为你自己的域名）：

文档中的{{< sitevar name="domain" nojs="example.com" >}}与{{< sitevar name="subdomain-authelia" nojs="auth" >}}是 Authelia 文档系统的变量占位符，本文已统一替换为example.com与auth的默认值，你可以按自己的域名环境全局替换。

在 Authelia 中注册 OpenID Connect 1.0 客户端

客户端注册配置

以下 YAML 是 Authelia 的 OpenID Connect 1.0 客户端配置 示例，位于 Authelia 主配置文件的identity_providers.oidc.clients列表下：

identity_providers: oidc: ## OpenID Connect 1.0 Provider 的其余必填配置写在这里。 ## 参见: docs/content/configuration/identity-providers/openid-connect/provider.md clients: - client_id: 'ezbookkeeping' client_name: 'ezBookkeeping' client_secret: '$pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng' # The digest of 'insecure_secret'. public: false authorization_policy: 'two_factor' require_pkce: true pkce_challenge_method: 'S256' redirect_uris: - 'https://ezbookkeeping.example.com/oauth2/callback' scopes: - 'openid' - 'profile' - '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'

客户端配置项逐项解读

client_id / client_name：client_id必须与 ezBookkeeping 侧配置完全一致，且必须在所有已注册客户端中唯一。它只能包含 RFC3986 Unreserved Characters FAQ）。

client_secret：客户端与 Authelia 共享的密钥，必须与 ezBookkeeping 侧配置的明文密钥一致。示例中配置的是明文insecure_secret的PBKDF2-SHA512 哈希摘要，这是 Authelia 强烈推荐的存储方式（明文存储已被标记为弃用）。注意：哈希值只用于 Authelia 的client_secret字段，ezBookkeeping 侧仍要配置明文原文。可用authelia crypto hash-pbkdf2一类命令生成哈希（详见 FAQ 中 client secret 生成指南）。若哈希计算成本过高导致客户端超时，可参考 Tuning the work factors 调整工作因子。

public: false：声明这是一个confidential（机密）客户端——ezBookkeeping 是服务端应用，能够安全保管密钥。机密客户端默认使用client_secret_basic认证（见下文）。若设为true则要求client_secret置空。

authorization_policy: 'two_factor'：该客户端专属的授权策略，可取one_factor、two_factor或 Provider 级authorization_policies中自定义的策略名。two_factor意味着用户登录 ezBookkeeping 时，Authelia 会强制完成双因素认证（如 TOTP / WebAuthn），这是与 Authelia 门户其他受保护资源一致的安全基线。注意此选项与访问控制规则（Access Control Rules）是两套独立机制，仅作用于授权请求。

require_pkce / pkce_challenge_method：强制要求 PKCE（RFC 7636），并指定挑战方法为S256。PKCE 用随机的code_verifier经 SHA-256 摘要后 Base64URL 编码得到code_challenge，在换取令牌时必须提供原始code_verifier，从而证明持有授权码的客户端就是发起授权请求的那一方，可有效缓解授权码拦截攻击。S256是官方文档强烈推荐的方法，plain仅应在客户端无法支持S256时使用。

redirect_uris：回调 URI 白名单，大小写敏感，仅允许http/https方案。ezBookkeeping 的 OAuth2 回调路径为https://ezbookkeeping.example.com/oauth2/callback。若客户端发起的授权请求携带的 redirect_uri 不在白名单内，Authelia 将直接拒绝并报错。

scopes：允许该客户端消费的 Scope。示例为openid、profile、email（这也是 Scope 定义文档 中三个最常用的标准 Scope）：

• openid：启用 OpenID Connect 1.0 语义，返回 ID Token 及iss、sub、aud、exp、auth_time等核心 Claim；
• profile：暴露用户的preferred_username、display_name、email等资料类 Claim；
• email：暴露email、email_verified、alt_emailsClaim。

response_types / grant_types：仅允许code响应类型与authorization_code授权类型，即标准的授权码流程（Authorization Code Flow）。官方文档明确建议只使用code，其余响应类型安全性较低。若只配置了client_credentials等其他授权类型，openid、offline等 Scope 将被禁止。

access_token_signed_response_alg / userinfo_signed_response_alg: 'none'：Access Token 与 UserInfo 响应均不签名（保持 Authelia 默认值），即 Access Token 为不透明令牌、UserInfo 返回普通 JSON。若改为非none值，Access Token 将按 RFC 9068 编码为 JWT，UserInfo 响应将变成签名 JWT，这两种能力多数客户端并不支持。

token_endpoint_auth_method: 'client_secret_basic'：客户端在 Token 端点使用 HTTP Basic Auth 提交凭证（RFC 6749 对机密客户端的默认要求）。这要求 Client ID 与 Secret 均只包含 URL 安全字符——这也是上面建议使用rfc3986字符集生成密钥的原因，部分客户端（含 ezBookkeeping 这类应用）不会对凭证做 URL 转义。

别忘了 Provider 级配置

上述片段只覆盖了客户端注册部分。Authelia 作为 OpenID Connect 1.0 Provider 还需要配置 Provider 级必填项，至少包括：

• hmac_secret：用于签名 JWT 的 HMAC 密钥，官方建议使用 64 位以上的随机字母数字串；
• jwks：至少一个 RSA 私钥（算法 RS256）用于签发令牌；
• 以及 issuer 相关的 URL 设置（Authelia 根 URL 即 OIDC Issuer）。

在 ezBookkeeping 中对接 Authelia

ezBookkeeping 提供两种配置方式：配置文件（ezbookkeeping.ini）与环境变量。两者等价，二选一即可。

方式一：配置文件

[server] domain = ezbookkeeping.example.com root_url = https://ezbookkeeping.example.com/ [auth] enable_oauth2_auth = true oauth2_provider = oidc oauth2_client_id = ezbookkeeping oauth2_client_secret = insecure_secret oauth2_use_pkce = true oidc_provider_base_url = https://auth.example.com enable_oidc_display_name = true oidc_custom_display_name = Authelia

配置项含义：

• [server]段：domain与root_url必须与应用的公开访问地址一致，OAuth2 回调会基于此生成；
• [auth]段：enable_oauth2_auth = true开启 OAuth2 登录；oauth2_provider = oidc指定使用 OpenID Connect；oauth2_client_id/oauth2_client_secret与 Authelia 侧一致；oauth2_use_pkce = true启用 PKCE（与 Authelia 的require_pkce: true相互匹配）；oidc_provider_base_url指向 Authelia 根地址（即 OIDC Issuer，ezBookkeeping 会据此自动发现.well-known/openid-configuration元数据）；enable_oidc_display_name = true与oidc_custom_display_name = Authelia让登录按钮显示为 "Authelia"。

方式二：环境变量

环境变量名由配置键名按EBK_前缀 + 大写 + 下划线规则映射而来：

EBK_SERVER_DOMAIN=ezbookkeeping.example.com EBK_SERVER_ROOT_URL=https://ezbookkeeping.example.com/ EBK_AUTH_ENABLE_OAUTH2_AUTH=true EBK_AUTH_OAUTH2_PROVIDER=oidc EBK_AUTH_OAUTH2_CLIENT_ID=ezbookkeeping EBK_AUTH_OAUTH2_CLIENT_SECRET=insecure_secret EBK_AUTH_OAUTH2_USE_PKCE=true EBK_AUTH_OIDC_PROVIDER_BASE_URL='https://auth.example.com' EBK_AUTH_ENABLE_OIDC_DISPLAY_NAME=true EBK_AUTH_OIDC_CUSTOM_DISPLAY_NAME=Authelia

方式三：Docker Compose

如果 ezBookkeeping 以容器方式部署，直接在 service 的environment中注入上述环境变量即可：

services: ezbookkeeping: environment: EBK_SERVER_DOMAIN=ezbookkeeping.example.com EBK_SERVER_ROOT_URL=https://ezbookkeeping.example.com/ EBK_AUTH_ENABLE_OAUTH2_AUTH=true EBK_AUTH_OAUTH2_PROVIDER=oidc EBK_AUTH_OAUTH2_CLIENT_ID=ezbookkeeping EBK_AUTH_OAUTH2_CLIENT_SECRET=insecure_secret EBK_AUTH_OAUTH2_USE_PKCE=true EBK_AUTH_OIDC_PROVIDER_BASE_URL='https://auth.example.com' EBK_AUTH_ENABLE_OIDC_DISPLAY_NAME=true EBK_AUTH_OIDC_CUSTOM_DISPLAY_NAME=Authelia

关键参数对照表

部署时请逐项核对两侧配置的一致性：

登录流程与底层原理

完成上述配置后，一次完整的 SSO 登录流程如下（对应 OpenID Connect 1.0 集成指南 描述的授权码流程）：

1. 用户访问 ezBookkeeping 并点击 "Authelia" 登录按钮；
2. ezBookkeeping 通过oidc_provider_base_url下的.well-known/openid-configuration发现 Authelia 的授权端点、令牌端点、JWKS 等元数据（Authelia 还提供.well-known/oauth-authorization-server元数据端点，二者路径均详见集成指南的 Endpoint Implementations 章节）；
3. ezBookkeeping 生成code_verifier与code_challenge，将用户重定向到 Authelia 授权端点（/api/oidc/authorization），携带client_id、redirect_uri、response_type=code、scope=openid profile email与 PKCE 参数；
4. 用户在 Authelia 门户完成登录与双因素认证，并（按策略）授予同意后，Authelia 将授权码经https://ezbookkeeping.example.com/oauth2/callback回传给 ezBookkeeping；
5. ezBookkeeping 在令牌端点（/api/oidc/token）以client_secret_basic提交凭证并附上code_verifier换取 ID Token 与 Access Token；
6. ezBookkeeping 校验 ID Token，并按需调用 UserInfo 端点（/api/oidc/userinfo）获取用户资料，建立本地会话。

关于用户身份绑定的重要提示

在 Scope 定义文档 的openid章节中，Authelia 官方明确指出：iss（签发方）与sub（主体）Claim 的组合是唯一被规范保证不会变化的用户标识，是链接本地账户的唯一可靠方式；而preferred_username、email等 Claim 只应被用于新账户的预置（provisioning），不应作为既有账户的绑定依据。ezBookkeeping 的账号绑定逻辑对sub/iss的依赖程度取决于其实现版本，接入时建议确认其使用稳定的 OIDC 标识绑定本地账户，以避免邮箱或用户名变更导致的账户错配风险。

安全纵深

• PKCE（S256）：本集成同时在 Authelia 侧require_pkce与 ezBookkeeping 侧oauth2_use_pkce开启，即使授权码被截获，攻击者也无法在缺少code_verifier的情况下换取令牌；
• 双因素强制：authorization_policy: 'two_factor'使所有经 OIDC 进入 ezBookkeeping 的登录都必须满足 Authelia 的双因素要求；
• 令牌最小化：access_token_signed_response_alg: 'none'与userinfo_signed_response_alg: 'none'保持不透明令牌 + 普通 JSON UserInfo，符合多数服务端应用（包括 ezBookkeeping）的解析习惯；
• 发现端点：ezBookkeeping 通过标准元数据发现（而非硬编码端点路径）获取 Authelia 的各端点地址，降低因端点路径变化导致的失效概率。

常见问题排查

1. 登录后回调被拒：检查redirect_uris是否与 ezBookkeeping 实际回调 URL 完全一致（大小写敏感），并确认domain/root_url配置与公网访问地址一致。
2. 令牌端点报 client 凭证错误：若 Client ID / Secret 含特殊字符，部分客户端不会按 RFC 6749 Appendix B 做 URL 转义（client_secret_basic与client_secret_post均受影响）。解决方法是改用仅含 RFC3986 Unreserved Characters 的随机串，或预先 URL 转义后再写入配置。
3. PKCE 校验失败：确认 ezBookkeeping 的oauth2_use_pkce = true与 Authelia 的pkce_challenge_method: 'S256'匹配，且两侧版本都支持 S256 变换。
4. 用户无法完成双因素：authorization_policy: 'two_factor'下，用户必须在 Authelia 中注册至少一种双因素方法，否则登录会被策略拒绝。
5. 自定义授权策略不生效：确认策略名在 Provider 级authorization_policies中定义，且客户端authorization_policy引用的名称拼写一致。

参考文档

• ezBookkeeping 集成指南（本文源文档）
• OpenID Connect 1.0 集成指南
• OpenID Connect 1.0 客户端配置
• OpenID Connect 1.0 Provider 配置
• OpenID Connect 1.0 Scope 与 Claim 定义
• OpenID Connect 1.0 常见问题（含 Client ID / Secret 生成）

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia