Authelia 集成 ezBookkeepingOpenID 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 集成并具备定位常见配置错误的排查能力。集成概览与测试版本本文对应的集成方案在以下版本组合下经过官方验证组件版本Autheliav4.39.13ezBookkeepingv1.2.0该集成属于社区维护级别文档 front matter 中support.level: community但integration: true即已被验证可正常工作。整体架构非常简单ezBookkeeping 作为 OpenID Connect 1.0 的 Relying Party依赖方把用户登录重定向到 AutheliaAuthelia 完成用户名/密码以及可选的双因素认证后通过标准授权码流程把身份信息交还给 ezBookkeeping。前置假设为便于说明本文示例使用以下占位值实际部署时请替换为你自己的域名项目值ezBookkeeping 应用根地址Application Root URLhttps://ezbookkeeping.example.com/Authelia 根地址Authelia Root URL即 OIDC Issuerhttps://auth.example.com/Client IDezbookkeepingClient Secretinsecure_secret文档中的{{ sitevar namedomain nojsexample.com }}与{{ sitevar namesubdomain-authelia nojsauth }}是 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_nameclient_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强制要求 PKCERFC 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 定义文档 中三个最常用的标准 Scopeopenid启用 OpenID Connect 1.0 语义返回 ID Token 及iss、sub、aud、exp、auth_time等核心 Claimprofile暴露用户的preferred_username、display_name、email等资料类 Claimemail暴露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: noneAccess Token 与 UserInfo 响应均不签名保持 Authelia 默认值即 Access Token 为不透明令牌、UserInfo 返回普通 JSON。若改为非none值Access Token 将按 RFC 9068 编码为 JWTUserInfo 响应将变成签名 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 中对接 AutheliaezBookkeeping 提供两种配置方式配置文件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 Connectoauth2_client_id/oauth2_client_secret与 Authelia 侧一致oauth2_use_pkce true启用 PKCE与 Authelia 的require_pkce: true相互匹配oidc_provider_base_url指向 Authelia 根地址即 OIDC IssuerezBookkeeping 会据此自动发现.well-known/openid-configuration元数据enable_oidc_display_name true与oidc_custom_display_name Authelia让登录按钮显示为 Authelia。方式二环境变量环境变量名由配置键名按EBK_前缀 大写 下划线规则映射而来EBK_SERVER_DOMAINezbookkeeping.example.com EBK_SERVER_ROOT_URLhttps://ezbookkeeping.example.com/ EBK_AUTH_ENABLE_OAUTH2_AUTHtrue EBK_AUTH_OAUTH2_PROVIDERoidc EBK_AUTH_OAUTH2_CLIENT_IDezbookkeeping EBK_AUTH_OAUTH2_CLIENT_SECRETinsecure_secret EBK_AUTH_OAUTH2_USE_PKCEtrue EBK_AUTH_OIDC_PROVIDER_BASE_URLhttps://auth.example.com EBK_AUTH_ENABLE_OIDC_DISPLAY_NAMEtrue EBK_AUTH_OIDC_CUSTOM_DISPLAY_NAMEAuthelia方式三Docker Compose如果 ezBookkeeping 以容器方式部署直接在 service 的environment中注入上述环境变量即可services: ezbookkeeping: environment: EBK_SERVER_DOMAINezbookkeeping.example.com EBK_SERVER_ROOT_URLhttps://ezbookkeeping.example.com/ EBK_AUTH_ENABLE_OAUTH2_AUTHtrue EBK_AUTH_OAUTH2_PROVIDERoidc EBK_AUTH_OAUTH2_CLIENT_IDezbookkeeping EBK_AUTH_OAUTH2_CLIENT_SECRETinsecure_secret EBK_AUTH_OAUTH2_USE_PKCEtrue EBK_AUTH_OIDC_PROVIDER_BASE_URLhttps://auth.example.com EBK_AUTH_ENABLE_OIDC_DISPLAY_NAMEtrue EBK_AUTH_OIDC_CUSTOM_DISPLAY_NAMEAuthelia关键参数对照表部署时请逐项核对两侧配置的一致性参数Authelia 侧ezBookkeeping 侧Client IDclient_id: ezbookkeepingoauth2_client_id ezbookkeepingClient Secretclient_secret哈希存储原文insecure_secretoauth2_client_secret insecure_secret明文回调地址redirect_uris: https://ezbookkeeping.example.com/oauth2/callback由domain/root_url自动生成PKCErequire_pkce: truepkce_challenge_method: S256oauth2_use_pkce true授权服务器地址Authelia 根 URL 即 Issueroidc_provider_base_url https://auth.example.com认证方式token_endpoint_auth_method: client_secret_basic客户端自动使用 Client Secret 认证登录流程与底层原理完成上述配置后一次完整的 SSO 登录流程如下对应 OpenID Connect 1.0 集成指南 描述的授权码流程用户访问 ezBookkeeping 并点击 Authelia 登录按钮ezBookkeeping 通过oidc_provider_base_url下的.well-known/openid-configuration发现 Authelia 的授权端点、令牌端点、JWKS 等元数据Authelia 还提供.well-known/oauth-authorization-server元数据端点二者路径均详见集成指南的 Endpoint Implementations 章节ezBookkeeping 生成code_verifier与code_challenge将用户重定向到 Authelia 授权端点/api/oidc/authorization携带client_id、redirect_uri、response_typecode、scopeopenid profile email与 PKCE 参数用户在 Authelia 门户完成登录与双因素认证并按策略授予同意后Authelia 将授权码经https://ezbookkeeping.example.com/oauth2/callback回传给 ezBookkeepingezBookkeeping 在令牌端点/api/oidc/token以client_secret_basic提交凭证并附上code_verifier换取 ID Token 与 Access TokenezBookkeeping 校验 ID Token并按需调用 UserInfo 端点/api/oidc/userinfo获取用户资料建立本地会话。关于用户身份绑定的重要提示在 Scope 定义文档 的openid章节中Authelia 官方明确指出iss签发方与sub主体Claim 的组合是唯一被规范保证不会变化的用户标识是链接本地账户的唯一可靠方式而preferred_username、email等 Claim 只应被用于新账户的预置provisioning不应作为既有账户的绑定依据。ezBookkeeping 的账号绑定逻辑对sub/iss的依赖程度取决于其实现版本接入时建议确认其使用稳定的 OIDC 标识绑定本地账户以避免邮箱或用户名变更导致的账户错配风险。安全纵深PKCES256本集成同时在 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 的各端点地址降低因端点路径变化导致的失效概率。常见问题排查登录后回调被拒检查redirect_uris是否与 ezBookkeeping 实际回调 URL 完全一致大小写敏感并确认domain/root_url配置与公网访问地址一致。令牌端点报 client 凭证错误若 Client ID / Secret 含特殊字符部分客户端不会按 RFC 6749 Appendix B 做 URL 转义client_secret_basic与client_secret_post均受影响。解决方法是改用仅含 RFC3986 Unreserved Characters 的随机串或预先 URL 转义后再写入配置。PKCE 校验失败确认 ezBookkeeping 的oauth2_use_pkce true与 Authelia 的pkce_challenge_method: S256匹配且两侧版本都支持 S256 变换。用户无法完成双因素authorization_policy: two_factor下用户必须在 Authelia 中注册至少一种双因素方法否则登录会被策略拒绝。自定义授权策略不生效确认策略名在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考