使用 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的底层原理可直接照搬落地到你的生产环境。测试版本与适用范围官方集成文档明确标注了该方案的实测版本组合组件版本Autheliav4.39.24Beszelv0.10.2集成支持级别community社区支持versions与integration字段均为 true说明该文档随版本持续验证维护。上述版本组合可正常工作的结论来自官方测试在你自己的环境升级 Authelia 或 Beszel 后建议以实际验证为准文档源见 beszel/index.md。前置假设Assumptions本文示例基于以下环境假设后续所有配置均以此为基础Beszel 应用根 URLhttps://beszel.example.com/Authelia 根 URLhttps://auth.example.com/该地址同时也是 OpenID Connect 1.0 IssuerClient IDbeszelClient Secretinsecure_secret说明官方文档中的域名通过文档变量sitevar替换默认值为example.com与子域auth本文直接展开为字面值以便复制使用。生产环境请替换为你自己的域名。一、在 Authelia 侧注册 OIDC 客户端Authelia 作为 OpenID Connect 1.0 Provider需要在配置文件的identity_providers.oidc.clients列表中注册 Beszel 对应的客户端。以下是官方集成文档给出的完整示例beszel/index.mdidentity_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 ExchangePKCERFC 7636。S256方法要求客户端将随机生成的code_verifier经 SHA-256 摘要并 Base64URL 编码后作为code_challenge发送到授权端点在换取 Token 时再提交原始code_verifier以证明对授权码的持有可有效缓解授权码拦截攻击。官方集成文档同时设置了这两项说明 Beszel 支持 PKCEpkce_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: noneAccess Token 与 UserInfo 响应均不签名。none表示 UserInfo 端点以application/json; charsetutf-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 ProviderWeb GUI官方文档指出配置 Beszel 只有一种方式通过其Web 图形界面Web GUI。具体步骤如下对应 beszel/index.md 的 Web GUI 小节登录 Beszel。进入设置面板访问https://beszel.example.com/_/#/settings。关闭DisableHide collection create and edit controls选项。点击users集合旁的齿轮图标选择Options编辑该集合。展开OAuth2区域。将Enable开关切换到开启状态。点击Add Provider。选择OpenID Connect。按以下内容配置各项参数配置项值Client IDbeszelClient secretinsecure_secretDisplay nameAutheliaAuth URLhttps://auth.example.com/api/oidc/authorizationToken URLhttps://auth.example.com/api/oidc/tokenFetch user info fromUser info URLUser info URLhttps://auth.example.com/api/oidc/userinfo点击页面底部的Save保存。为什么是这三个端点Beszel 侧填写的三个 URL 正是 Authelia OpenID Connect 1.0 Provider 的授权端点、Token 端点与 UserInfo 端点。这些路径在源码中统一定义其根路径为/api/oidc见 internal/oidc/const.goEndpointPathRoot /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.gohttps://auth.example.com/.well-known/openid-configurationhttps://auth.example.com/.well-known/oauth-authorization-server支持 OpenID Connect Discovery 的客户端可以直接从这两个端点自动发现上述全部端点无需手工填写。Beszel 目前要求手工填写 Auth/Token/UserInfo 三个 URL按上述表格填写即可。三、登录流程与安全要点完成两侧配置后用户的登录流程为用户访问 Beszel 并选择使用 Authelia 登录。Beszel 将用户重定向到 Authelia 的授权端点/api/oidc/authorization携带client_idbeszel、redirect_urihttps://beszel.example.com/api/oauth2-redirect、response_typecode、scopeopenid email profile以及 PKCE 的code_challengeS256。用户未登录时Authelia 展示其登录页要求完成用户名密码认证并根据authorization_policy: two_factor进一步要求双因素认证如 TOTP、WebAuthn 等。认证通过后Authelia 依据该客户端的consent_mode向用户展示同意授权页列出该客户端请求的权限用户确认后签发授权码并重定向回 Beszel 的/api/oauth2-redirect。Beszel 使用授权码 code_verifierclient_secretHTTP 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 中有对应断言。延伸阅读Beszel OIDC 集成文档本文依据的官方文档OpenID Connect 1.0 集成介绍端点实现、响应类型/模式、客户端认证方式、支持算法等协议细节OpenID Connect 1.0 客户端配置指南clients下全部配置项的完整定义与默认值OpenID Connect 1.0 Provider 配置指南Issuer、授权策略、lifespans、claims 策略等 Provider 级配置OpenID Connect 1.0 Claims 指南scope 定义与各 Claims 的语义OpenID Connect 1.0 常见问题Client ID/Secret 生成、consent 行为等【免费下载链接】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），仅供参考