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 小节）：

• Authelia：v4.39.24
• Zipline：v4.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）

官方示例基于以下假设，实际部署时请替换为你的真实域名与凭据：

注意：example.com为文档占位域名，文中的{{< sitevar >}}变量可被替换为站点配置变量（参见docs/content/integration/openid-connect/clients/zipline/index.md的 Assumptions 小节）。insecure_secret仅用于演示，生产环境必须使用安全随机生成的密钥。

配置前的关键阅读

在动手配置任何 OpenID Connect 1.0 客户端之前，官方 oidc-common 模板 强调了以下几点通用注意事项：

1. client_id的约束：
   • 每个客户端必须使用全局唯一的client_id；
   • 长度不得超过 100 字符；
   • 只能包含 RFC3986 Unreserved Characters）；
   • 文档示例值仅用于可读性演示，生产环境建议使用 64 位随机字符。
2. client_secret的存储：
   • 文档示例值仅用于演示，生产环境绝对不要使用该值；
   • 强烈推荐在 Authelia 配置中以哈希形式存储密钥（即下面配置中的$pbkdf2-sha512$...值）；
   • 明文存储虽然"技术上"可用，但已被正式弃用（见 FAQ 之 Plaintext）；
   • 哈希的 work factor 过高会导致客户端认证超时，需要按硬件能力调优。
3. 配置完整性：本文的 YAML 只展示客户端注册部分，你必须同时完成 OpenID Connect 1.0 Provider 配置（issuer、密钥、令牌生命周期等全局项），并且建议通读 OpenID Connect 1.0 Clients 配置文档 了解全部可用选项及其影响。

在 Authelia 中注册 OIDC 客户端

生成安全的 Client ID 与 Client Secret

不要直接使用示例中的insecure_secret。Authelia 提供了内置命令生成随机凭据：

• 生成 72 字符、仅含 RFC3986 无保留字符的Client ID（Bare-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（详见 FAQ：Tuning 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 必需 scope；offline_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: 'none'：Access Token 与 UserInfo 响应不进行 JWT 签名，以普通 JSON 形式返回。none是这两个选项的默认值（参见 clients.md 对应小节），也是多数客户端唯一支持的取值。
• token_endpoint_auth_method: 'client_secret_post'：Zipline 在令牌端点通过 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设为S256（Zipline 支持与否需以实际版本为准，参见 require_pkce / pkce_challenge_method 选项）。

在 Zipline 中配置 OIDC

Zipline 侧只有一种配置方式：通过Web 管理界面（Web GUI）完成（见 Zipline 集成文档 的 Application 小节）。操作步骤如下：

1. 进入 Zipline 的Server Settings（服务器设置）。
2. 打开OAuth Registration（OAuth 注册）功能开关。
3. 配置以下选项：
   • OIDC Client ID：zipline
   • OIDC Client Secret：insecure_secret（生产环境替换为你生成的随机明文 Secret）
   • OIDC Authorize URL：https://auth.example.com/api/oidc/authorization
   • OIDC Token URL：https://auth.example.com/api/oidc/token
   • OIDC Userinfo URL：https://auth.example.com/api/oidc/userinfo
   • OIDC Redirect URL：可以留空。但需要注意，Zipline 默认生成的重定向 URL 使用 HTTP；如果你没有在 Core 设置中开启Return HTTPS URLs，这会直接影响 OIDC Redirect URL 的协议，务必确保最终回调地址与 Authelia 侧redirect_uris中的https://zipline.example.com/api/auth/oauth/oidc保持一致。
4. 点击Save保存。

底层端点与原理佐证

上述 Web GUI 中填写的三个端点 URL 均来自 Authelia 的 OIDC 端点实现，其路径定义可参见 OpenID Connect 1.0 集成介绍 的 Endpoint Implementations 小节：

这些端点也可通过发现端点自动获取：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 响应的实现。

一个典型的登录流程是：

1. 用户访问 Zipline，Zipline 将浏览器重定向到authorization端点，携带client_id、redirect_uri、scope=openid offline_access email profile、response_type=code；
2. 用户在 Authelia 门户完成认证（根据authorization_policy可能要求 1FA 或 2FA）；
3. Authelia 将授权码回传到 Zipline 的redirect_uri；
4. Zipline 使用client_secret_post方式向token端点换取 Access Token / Refresh Token / ID Token；
5. Zipline 通过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