Authelia 与 Zipline 集成指南：通过 OpenID Connect 1.0 实现单点登录

Authelia 与 Zipline 集成指南通过 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 官方集成手册Zipline 集成文档编写讲解如何将 Zipline一款开源的分享面板应用接入 Authelia 的 OpenID Connect 1.0 Provider实现统一身份认证SSO。读完本文你将掌握在 Autheliaconfiguration.yml中注册 OIDC 客户端、在 Zipline Web 管理界面填写 OIDC 端点与凭据的完整流程并理解各配置项如redirect_uris、scopes、token_endpoint_auth_method、签名算法的底层含义与安全建议。集成概览与测试版本本集成示例已经在以下版本组合上完成验证见 Zipline 集成文档 的 Tested Versions 小节Autheliav4.39.24Ziplinev4.2.3集成场景为用户访问 Zipline 时Zipline 作为 OpenID Connect 1.0 Relying Party依赖方将认证请求转发给 Authelia用户在 Authelia 门户完成登录可含多因素认证后Authelia 向 Zipline 签发令牌Zipline 据此建立本地会话。Authelia 本身通过了 OpenID Foundation 的 OpenID Certified™ 认证Basic OP / Implicit OP / Hybrid OP / Form Post OP / Config OP 五个 profile其 OIDC 端点的实现细节可参考 OpenID Connect 1.0 集成介绍。配置前提Assumptions官方示例基于以下假设实际部署时请替换为你的真实域名与凭据项目示例值应用根 URLZiplinehttps://zipline.example.com/Authelia 根 URLhttps://auth.example.com/Client IDziplineClient Secretinsecure_secret注意example.com为文档占位域名文中的{{ sitevar }}变量可被替换为站点配置变量参见docs/content/integration/openid-connect/clients/zipline/index.md的 Assumptions 小节。insecure_secret仅用于演示生产环境必须使用安全随机生成的密钥。配置前的关键阅读在动手配置任何 OpenID Connect 1.0 客户端之前官方 oidc-common 模板 强调了以下几点通用注意事项client_id的约束每个客户端必须使用全局唯一的client_id长度不得超过 100 字符只能包含 RFC3986 Unreserved Characters文档示例值仅用于可读性演示生产环境建议使用 64 位随机字符。client_secret的存储文档示例值仅用于演示生产环境绝对不要使用该值强烈推荐在 Authelia 配置中以哈希形式存储密钥即下面配置中的$pbkdf2-sha512$...值明文存储虽然技术上可用但已被正式弃用见 FAQ 之 Plaintext哈希的 work factor 过高会导致客户端认证超时需要按硬件能力调优。配置完整性本文的 YAML 只展示客户端注册部分你必须同时完成 OpenID Connect 1.0 Provider 配置issuer、密钥、令牌生命周期等全局项并且建议通读 OpenID Connect 1.0 Clients 配置文档 了解全部可用选项及其影响。在 Authelia 中注册 OIDC 客户端生成安全的 Client ID 与 Client Secret不要直接使用示例中的insecure_secret。Authelia 提供了内置命令生成随机凭据生成 72 字符、仅含 RFC3986 无保留字符的Client IDBare-Metal 方式authelia crypto rand --length 72 --charset rfc3986同时生成随机Client Secret 及其 PBKDF2 哈希Docker 方式docker run --rm authelia/authelia:latest authelia crypto hash generate pbkdf2 --variant sha512 --random --random.length 72 --random.charset rfc3986该命令会打印出明文 Secret用于填入 Zipline以及可写入 Authelia 配置的哈希值。若使用的字符集在 URL 编码后会产生差异命令还会额外打印预编码版本详见 FAQ如何生成 Client ID / Secret。提示当 secret 以哈希形式存储时Authelia 每次收到客户端认证请求都要执行哈希运算。若客户端操作超时可先测量当前 work factor 的耗时time authelia crypto hash generate pbkdf2 --variant sha512 --iterations 310000 --password insecure_password再酌情降低--iterations详见 FAQTuning work factors。Authelia 客户端配置示例在configuration.yml的identity_providers.oidc.clients列表中加入以下条目该片段完整继承自 Zipline 集成文档identity_providers: oidc: ## OpenID Connect 1.0 Provider 的其他必需配置项写在这里。 ## 参见: docs/content/configuration/identity-providers/openid-connect/provider.md clients: - client_id: zipline client_name: Zipline client_secret: $pbkdf2-sha512$310000$c8p78n7pUMln0jzvd4aK4Q$JNRBzwAo0ek5qKn50cFzzvE9RXV88h1wJn5KGiHrD0YKtZaR/nCb2CJPOsKaPK0hjf.9yHxzQGZziziccp6Yng # 这是 insecure_secret 的哈希摘要。 public: false require_pkce: false pkce_challenge_method: redirect_uris: - https://zipline.example.com/api/auth/oauth/oidc scopes: - openid - offline_access - email - profile response_types: - code grant_types: - refresh_token - authorization_code access_token_signed_response_alg: none userinfo_signed_response_alg: none token_endpoint_auth_method: client_secret_post关键配置项解析以下参数的解释依据 OpenID Connect 1.0 Clients 配置文档client_id必填string必须与 Zipline 中配置的 Client ID 完全一致长度 ≤ 100 字符、仅含 RFC3986 无保留字符、全局唯一。client_name可选显示在 Authelia 用户界面中的友好名称缺省时与client_id相同。client_secret情境必填Authelia 与应用共享的密钥必须与 Zipline 中填写的明文 Secret 匹配文档示例中的哈希值对应明文insecure_secret$pbkdf2-sha512$310000$...前缀表示 PBKDF2-SHA512、310000 次迭代。public: false声明本客户端为机密型confidential客户端可以安全保管密钥。若设为true则要求client_secret为空字符串参见 public 选项。redirect_uris必填列表合法的回调 URI 白名单其他回调一律视为不安全并拒绝授权。注意URI 大小写敏感、必须带http或httpsscheme参见 redirect_uris 选项。此处必须指向 Zipline 的 OIDC 回调路径https://zipline.example.com/api/auth/oauth/oidc。scopes允许该客户端申请的权限范围。openid是 OIDC 必需 scopeoffline_access用于申请刷新令牌email、profile用于获取用户邮箱与基础资料声明。默认值为openid,groups,profile,email参见 scopes 选项。response_types: [code]仅启用 Authorization Code Flow。这是官方推荐的最安全响应类型参见 response_types 选项。grant_types允许的授权类型。authorization_code为授权码流程refresh_token允许 Zipline 使用offline_access刷新令牌参见 grant_types 选项。access_token_signed_response_alg: none/userinfo_signed_response_alg: noneAccess Token 与 UserInfo 响应不进行 JWT 签名以普通 JSON 形式返回。none是这两个选项的默认值参见 clients.md 对应小节也是多数客户端唯一支持的取值。token_endpoint_auth_method: client_secret_postZipline 在令牌端点通过 HTTP POST 请求体携带 Client ID 与 Secret 完成客户端认证。Authelia 支持的客户端认证方法还包括client_secret_basic、client_secret_jwt、private_key_jwt等参见 Client Authentication Method 与 token_endpoint_auth_method 选项。require_pkce: false/pkce_challenge_method: 不强制 Zipline 使用 PKCE。如需强化安全可将require_pkce设为true并把pkce_challenge_method设为S256Zipline 支持与否需以实际版本为准参见 require_pkce / pkce_challenge_method 选项。在 Zipline 中配置 OIDCZipline 侧只有一种配置方式通过Web 管理界面Web GUI完成见 Zipline 集成文档 的 Application 小节。操作步骤如下进入 Zipline 的Server Settings服务器设置。打开OAuth RegistrationOAuth 注册功能开关。配置以下选项OIDC Client IDziplineOIDC Client Secretinsecure_secret生产环境替换为你生成的随机明文 SecretOIDC Authorize URLhttps://auth.example.com/api/oidc/authorizationOIDC Token URLhttps://auth.example.com/api/oidc/tokenOIDC Userinfo URLhttps://auth.example.com/api/oidc/userinfoOIDC Redirect URL可以留空。但需要注意Zipline 默认生成的重定向 URL 使用 HTTP如果你没有在 Core 设置中开启Return HTTPS URLs这会直接影响 OIDC Redirect URL 的协议务必确保最终回调地址与 Authelia 侧redirect_uris中的https://zipline.example.com/api/auth/oauth/oidc保持一致。点击Save保存。底层端点与原理佐证上述 Web GUI 中填写的三个端点 URL 均来自 Authelia 的 OIDC 端点实现其路径定义可参见 OpenID Connect 1.0 集成介绍 的 Endpoint Implementations 小节端点路径Authorization授权https://auth.example.com/api/oidc/authorizationToken令牌https://auth.example.com/api/oidc/tokenUserInfo用户信息https://auth.example.com/api/oidc/userinfo其他Introspection / Revocation 等/api/oidc/introspection、/api/oidc/revocation、/api/oidc/device-authorization、/api/oidc/pushed-authorization-request、/jwks.json这些端点也可通过发现端点自动获取https://auth.example.com/.well-known/openid-configuration或https://auth.example.com/.well-known/oauth-authorization-server。在源码层面这些端点的处理逻辑位于 internal/handlers 目录例如 handler_oauth2_authorization.go、handler_oauth2_token.go、handler_oauth2_oidc_userinfo.go 等文件分别承载授权请求、令牌签发与 UserInfo 响应的实现。一个典型的登录流程是用户访问 ZiplineZipline 将浏览器重定向到authorization端点携带client_id、redirect_uri、scopeopenid offline_access email profile、response_typecode用户在 Authelia 门户完成认证根据authorization_policy可能要求 1FA 或 2FAAuthelia 将授权码回传到 Zipline 的redirect_uriZipline 使用client_secret_post方式向token端点换取 Access Token / Refresh Token / ID TokenZipline 通过userinfo端点或 ID Token获取用户资料建立本地会话会话过期后可用refresh_token授权类型静默续期。验证与常见排错回调地址不匹配Zipline 生成的 Redirect URL 默认基于 HTTP若未开启Return HTTPS URLs回调协议与 Authelia 侧redirect_uris中的 HTTPS 地址不一致会导致授权失败。请确保两端协议、主机、路径完全一致redirect_uris是大小写敏感的精确匹配。客户端认证失败确认 Authelia 配置中的client_secret哈希对应 Zipline 中填写的明文 Secret。若使用明文存储已被弃用要留意未来版本将不再支持建议改用上文介绍的哈希生成命令。登录超时当 secret 以 PBKDF2 哈希存储且迭代次数过高时客户端认证可能超时可参考 Tuning work factors 适当降低 work factor。令牌刷新问题确认 Zipline 申请的offline_accessscope 与 Authelia 侧scopes列表一致且grant_types中包含refresh_token。Authelia 在刷新流程中会校验 scope 与 audience 不得超过先前授权范围详见 OpenID Connect 1.0 集成介绍。接口行为差异本集成示例关闭了 PKCE 强制要求、Access Token 与 UserInfo 签名none这些是按 Zipline 兼容性选择的保守配置。若你的 Zipline 版本支持更严格的安全选项如 PKCE S256可在验证基础流程后逐步加固。参考文档Zipline 集成文档本文依据OpenID Connect 1.0 集成介绍OpenID Connect 1.0 客户端配置OpenID Connect 1.0 Provider 配置OpenID Connect 1.0 常见问题凭据生成与密钥存储OpenID Connect 1.0 声明与 Scope 定义【免费下载链接】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），仅供参考