使用 Authelia OpenID Connect 1.0 为 Beszel 配置单点登录（SSO）完整指南-开发者社区

使用 Authelia OpenID Connect 1.0 为 Beszel 配置单点登录（SSO）完整指南

【免费下载链接】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 官方集成文档，完整演示如何将轻量级服务器监控面板 [Beszel] 接入 Authelia 的 OpenID Connect 1.0 Provider，实现以 Authelia 为身份源的统一单点登录与双因素认证。读完本文，你将掌握：在 Authelia 侧注册 OIDC 客户端（Client）的完整 YAML 配置、在 Beszel Web 管理界面中逐项填写 OIDC 端点参数的具体步骤，以及 Authorization Code + PKCE 流程背后 Authelia 端点实现（internal/oidc/const.go）与相关测试（如 handler_oauth2_authorization_test.go）的底层原理，可直接照搬落地到你的生产环境。

测试版本与适用范围

官方集成文档明确标注了该方案的实测版本组合：

组件	版本
Authelia	v4.39.24
Beszel	v0.10.2

集成支持级别：community（社区支持），versions与integration字段均为 true，说明该文档随版本持续验证维护。
上述版本组合可正常工作的结论来自官方测试；在你自己的环境升级 Authelia 或 Beszel 后，建议以实际验证为准（文档源见 beszel/index.md）。

前置假设（Assumptions）

本文示例基于以下环境假设，后续所有配置均以此为基础：

Beszel 应用根 URL：https://beszel.example.com/
Authelia 根 URL：https://auth.example.com/（该地址同时也是 OpenID Connect 1.0 Issuer）
Client ID：beszel
Client Secret：insecure_secret

说明：官方文档中的域名通过文档变量（sitevar）替换，默认值为example.com与子域auth，本文直接展开为字面值以便复制使用。生产环境请替换为你自己的域名。

一、在 Authelia 侧注册 OIDC 客户端

Authelia 作为 OpenID Connect 1.0 Provider，需要在配置文件的identity_providers.oidc.clients列表中注册 Beszel 对应的客户端。以下是官方集成文档给出的完整示例（beszel/index.md）：

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: 'beszel' client_name: 'Beszel' 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://beszel.example.com/api/oauth2-redirect' scopes: - 'openid' - 'email' - 'profile' 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'

关键配置项逐项解析

以上配置中每个字段的含义均可与 Authelia 的 OpenID Connect 1.0 客户端配置指南一一对应：

client_id（必填，字符串）：客户端的唯一标识，长度不超过 100 字符，仅允许 RFC3986 Unreserved Characters，且必须与其他客户端完全唯一。官方建议使用半长的随机字母数字串。该值必须与 Beszel 中填写的 Client ID 完全一致。
client_name（可选，默认与client_id相同）：显示在 Authelia 用户界面（如同意授权页）上的友好名称。
client_secret（机密客户端必填）：Authelia 与应用共享的密钥，必须与应用侧配置的密钥一致。示例中的值$pbkdf2-sha512$310000$...是明文insecure_secret的 PBKDF2-SHA512 哈希摘要（配置模板中同样内嵌了该摘要示例，见 config.template.yml）。推荐做法：配置文件中存放的是密码学摘要而非明文；如需生成新的摘要，可使用authelia crypto hash generate命令（命令定义见 internal/commands/const.go）。
public: false：声明该客户端为机密（confidential）客户端类型，即有能力安全保管凭据。机密客户端在 Token 端点必须携带凭据进行认证（详见下文token_endpoint_auth_method）。如果设置为true（公开客户端，适用于 SPA/CLI），则client_secret必须留空。
authorization_policy: 'two_factor'：该客户端在授权请求时要求的认证强度策略，取值为one_factor、two_factor，或在 Provider 的authorization_policies中自定义的策略名。two_factor意味着用户必须完成双因素认证才能完成授权。注意该策略仅作用于 OIDC 授权请求本身，与 Authelia 的访问控制规则（Access Control Rules）是两套独立机制。
require_pkce: true与pkce_challenge_method: 'S256'：强制该客户端必须使用 Proof Key for Code Exchange（PKCE，RFC 7636）。S256方法要求客户端将随机生成的code_verifier经 SHA-256 摘要并 Base64URL 编码后作为code_challenge发送到授权端点，在换取 Token 时再提交原始code_verifier以证明对授权码的持有，可有效缓解授权码拦截攻击。官方集成文档同时设置了这两项，说明 Beszel 支持 PKCE；pkce_challenge_method一旦指定，等效于同时启用require_pkce。
redirect_uris：合法的回调 URI 列表，大小写敏感，scheme 必须是http或https。Beszel 的回调地址为https://beszel.example.com/api/oauth2-redirect，这是 Beszel 内置的 OAuth2 重定向端点。凡是不在此列表中的回调地址，Authelia 都会直接拒绝授权请求。
scopes：允许该客户端请求的权限范围，此处为openid、email、profile。各 scope 对应的 Claims 语义可参考 OpenID Connect 1.0 Claims 指南：
- openid：启用 OpenID Connect 1.0 语义，签发 ID Token，并返回iss、sub、aud、exp、iat、auth_time、amr等核心 Claims；其中sub是基于 RFC4122 UUID V4 的不透明用户标识，与iss组合是关联用户账号的唯一可靠方式。
- email：返回用户的邮箱相关 Claims（如email、email_verified）。
- profile：返回用户资料 Claims（如preferred_username、name等）。
response_types: ['code']：仅使用 Authorization Code Flow 响应类型，这是官方推荐的最安全的响应类型。使用code时默认允许form_post与query两种响应模式。
grant_types: ['authorization_code']：允许该客户端使用的授权类型，即标准 OAuth 2.0 授权码流程。
access_token_signed_response_alg: 'none'与userinfo_signed_response_alg: 'none'：Access Token 与 UserInfo 响应均不签名。none表示 UserInfo 端点以application/json; charset=utf-8的纯 JSON 返回（详见 OpenID Connect 1.0 集成介绍中的响应格式表）。这与 Beszel 端"Fetch user info from: User info URL"的取用户信息方式相吻合。
token_endpoint_auth_method: 'client_secret_basic'：客户端在 Token 端点使用 HTTP Basic Auth 携带client_secret进行认证，这是机密客户端的标准认证方式。Authelia 支持的全部客户端认证方式（client_secret_basic、client_secret_post、client_secret_jwt、private_key_jwt等）见集成介绍中的 Client Authentication Method 表格。

一个可以对照的完整客户端配置模板

如果你的 Beszel 或同类应用需要更多高级能力（如刷新令牌、自定义 audience、consent 模式、JARM、JWE 加密等），可以参考 Authelia 配置模板中展示的完整字段集（config.template.yml），以及客户端配置指南中对每个选项的完整定义。

二、在 Beszel 侧配置 OIDC Provider（Web GUI）

官方文档指出，配置 Beszel 只有一种方式：通过其Web 图形界面（Web GUI）。具体步骤如下（对应 beszel/index.md 的 Web GUI 小节）：

登录 Beszel。
进入设置面板，访问https://beszel.example.com/_/#/settings。
关闭（Disable）Hide collection create and edit controls选项。
点击users集合旁的齿轮图标，选择Options编辑该集合。
展开OAuth2区域。
将Enable开关切换到开启状态。
点击Add Provider。
选择OpenID Connect。
按以下内容配置各项参数：

配置项	值
Client ID	`beszel`
Client secret	`insecure_secret`
Display name	`Authelia`
Auth URL	`https://auth.example.com/api/oidc/authorization`
Token URL	`https://auth.example.com/api/oidc/token`
Fetch user info from	`User info URL`
User info URL	`https://auth.example.com/api/oidc/userinfo`

点击页面底部的Save保存。

为什么是这三个端点？

Beszel 侧填写的三个 URL 正是 Authelia OpenID Connect 1.0 Provider 的授权端点、Token 端点与 UserInfo 端点。这些路径在源码中统一定义，其根路径为/api/oidc（见 internal/oidc/const.go）：

EndpointPathRoot = "/api/oidc" EndpointPathAuthorization = EndpointPathRoot + "/" + EndpointAuthorization // /api/oidc/authorization EndpointPathToken = EndpointPathRoot + "/" + EndpointToken // /api/oidc/token EndpointPathUserinfo = EndpointPathRoot + "/" + EndpointUserinfo // /api/oidc/userinfo

路由在 internal/server/handlers.go 中注册：授权端点由OAuth2AuthorizationGET处理器响应，Token 端点、UserInfo 端点均有对应的处理器（分别见 handler_oauth2_authorization.go、handler_oauth2_token.go、handler_oauth2_oidc_userinfo.go）。这些端点路径同样被对应的单元测试固定引用，例如 handler_oauth2_token_test.go 中定义的testOIDCTokenEndpoint = "https://login.example.com:8080/api/oidc/token"，与官方文档的端点路径完全一致。

此外，Authelia 还提供两个 Well-Known 发现端点（同样定义于 internal/oidc/const.go）：

https://auth.example.com/.well-known/openid-configuration
https://auth.example.com/.well-known/oauth-authorization-server

支持 OpenID Connect Discovery 的客户端可以直接从这两个端点自动发现上述全部端点，无需手工填写。Beszel 目前要求手工填写 Auth/Token/UserInfo 三个 URL，按上述表格填写即可。

三、登录流程与安全要点

完成两侧配置后，用户的登录流程为：

用户访问 Beszel 并选择"使用 Authelia 登录"。
Beszel 将用户重定向到 Authelia 的授权端点/api/oidc/authorization，携带client_id=beszel、redirect_uri=https://beszel.example.com/api/oauth2-redirect、response_type=code、scope=openid email profile以及 PKCE 的code_challenge（S256）。
用户未登录时，Authelia 展示其登录页，要求完成用户名密码认证，并根据authorization_policy: 'two_factor'进一步要求双因素认证（如 TOTP、WebAuthn 等）。
认证通过后，Authelia 依据该客户端的consent_mode向用户展示同意授权页（列出该客户端请求的权限），用户确认后签发授权码并重定向回 Beszel 的/api/oauth2-redirect。
Beszel 使用授权码 +code_verifier+client_secret（HTTP Basic）调用 Token 端点/api/oidc/token换取 ID Token 与 Access Token。
Beszel 调用 UserInfo 端点/api/oidc/userinfo（携带 Access Token）获取用户资料，完成本地账号关联与会话建立。

几点值得注意的安全与运维要点：

Client Secret 应使用强随机值，并参考 Authelia 的 Client Identifier / Secret 生成 FAQ 中推荐的方式生成；官方集成文档中的insecure_secret仅为演示用途，生产环境务必替换。
PKCE 已开启（require_pkce: true、pkce_challenge_method: 'S256'），即使机密客户端的client_secret泄露，攻击者仍需持有code_verifier才能兑换授权码，这是纵深防御的体现。
redirect_uris必须精确匹配：Authelia 对回调 URI 做大小写敏感的精确匹配，任何未注册的回调都会被拒绝并产生错误，切勿在 Beszel 与 Authelia 两侧填写不一致的回调地址。
若你的部署将 Authelia 暴露在反代之后，请确保上述/api/oidc/*路径与/.well-known/*路径被正确代理转发，且保持 HTTPS，因为 OIDC 的令牌与凭据都依赖传输层安全。

四、验证配置是否生效

配置完成后，可以按以下方式验证：

访问https://beszel.example.com，点击登录并选择 Authelia 作为 OIDC Provider，确认能够跳转到https://auth.example.com完成认证。
使用浏览器开发者工具观察重定向链，确认授权码正确回跳至https://beszel.example.com/api/oauth2-redirect?code=...。
若需要排查端点可达性，可在浏览器直接访问https://auth.example.com/.well-known/openid-configuration，确认返回的 JSON 中包含authorization_endpoint、token_endpoint、userinfo_endpoint且与上文表格中的路径一致（该元数据在 handler_oauth2_wellknown_test.go 中有对应断言）。