ToolJet 配置 GitHub 单点登录（SSO）：OAuth App 注册、环境变量与 ssoUserInfo 实战指南

ToolJet 配置 GitHub 单点登录（SSO）：OAuth App 注册、环境变量与 ssoUserInfo 实战指南

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

ToolJet 内置了对 GitHub OAuth 2.0 的单点登录支持，允许实例管理员通过 GitHub 账号或 GitHub Enterprise 账号一键登录工作区。本文基于 ToolJet 2.50.0-LTS 文档与仓库源码，完整讲解从 ToolJet 管理界面启用 GitHub SSO、在 GitHub Developer settings 注册 OAuth App、回填凭据、通过环境变量设置默认 SSO，以及如何在应用内通过globals.currentUser.ssoUserInfo读取 GitHub 用户信息并调用 GitHub API 的全过程。读完本文，你将能够独立为自托管 ToolJet 实例配置可用的 GitHub 登录入口，并在低代码应用中安全使用用户授权令牌。

一、GitHub SSO 的工作原理与仓库实现

GitHub SSO 走的是标准 OAuth 2.0 Authorization Code 流程：用户在 ToolJet 登录页点击 GitHub 按钮后，被重定向到 GitHub（或 GitHub Enterprise）授权页面；授权通过后 GitHub 携带code回调 ToolJet；ToolJet 后端用client_id、client_secret和code换取access_token，再用该令牌拉取用户资料完成登录与建号。

在 git-oauth.service.ts 中可以清楚地看到这条调用链：

• 换取令牌：POST {hostName || 'https://github.com'}/login/oauth/access_token，请求体携带client_id、client_secret与code（见#getAuthUrl与signIn）；
• 获取用户资料：GET {hostName ? hostName + '/api/v3' : 'https://api.github.com'}/user，请求头使用Authorization: token <access_token>；
• 邮箱兜底：当用户未公开邮箱时，GitHub 的/user接口返回的email为空，ToolJet 会额外调用{...}/user/emails找到primary邮箱，确保账号能拿到有效邮箱（见#getEmailId）；
• 用户信息透传：#getUserDetails将 GitHub 返回的完整response与access_token合并为userinfoResponse，即后续暴露给前端ssoUserInfo的数据来源。

从源码结构可以看出，hostName是否配置决定了整个请求走 GitHub 公有云还是 GitHub Enterprise 的 API 端点，这也是下文第 5 步“Host Name”字段存在的根本原因。

二、在 ToolJet 中启用 GitHub SSO 并生成 Redirect URL

1. 登录 ToolJet 控制台，点击左侧边栏底部的Settings（⚙️），进入Workspace Settings。
2. 在Workspace Settings的侧边栏中选择Workspace login。右侧会列出多种 SSO 客户端的开关，所有开关默认关闭。找到GitHub对应的开关并打开，会弹出包含 Host name、Client ID、Client secret 等输入项的配置弹窗。
3. 弹窗左上角有一个启用开关，将其打开后，先不填写任何参数，直接点击Save changes按钮。此时 ToolJet 会生成一个Redirect URL（回调地址），这个地址将在下一步注册 GitHub OAuth App 时使用。

生成后的 Redirect URL 格式为<host>/sso/git，即“你的 ToolJet 实例地址 +/sso/git”。例如实例地址为https://tooljet.example.com，则回调地址为https://tooljet.example.com/sso/git。后端会在此路径接收 GitHub 的回调并完成code到access_token的兑换。

三、在 GitHub Developer settings 注册 OAuth App

1. 打开 GitHub 的Developer settings，进入OAuth Apps页面，点击New OAuth App创建新的 OAuth App。
2. 依次填写以下字段：
   • App Name：应用名称，例如ToolJet；
   • Homepage URL：ToolJet 实例的首页地址；
   • Authorization callback URL：必须填写上一步在 ToolJet 中生成的Redirect URL（即<host>/sso/git），这是 GitHub 授权后回调的地址，填错会导致登录失败。
3. 点击Register application完成创建。

注册完成后：

• Client ID由 GitHub 自动生成，用于标识你的应用；
• 点击Generate a new client secret按钮生成Client Secret，用于后端与 GitHub 交换令牌时验证身份，该值只会完整显示一次，请妥善保存。

四、回填凭据并完成配置

回到 ToolJet 的 GitHub SSO 设置弹窗，将 GitHub 上获取的Client ID和Client Secret填入对应输入框。

关于 Client Secret 的安全存储：从 login-configs/util.service.ts 可以看到，ToolJet 后端在保存 SSO 配置时会遍历配置项，将所有键名包含secret的字段通过EncryptionService进行加密后再写入数据库；而在对外返回配置时会做对称的解密，并在构造前端可见配置时通过buildConfigs过滤掉含secret的键（见 buildConfigs），因此客户端永远不会收到明文密钥。这意味着在界面中保存的密钥是加密落库的，与后文通过环境变量注入的方式在安全级别上有所区别。

五、GitHub Enterprise 自托管：配置 Host Name

如果你使用的是自托管的GitHub Enterprise，需要在弹窗中填写Host Name。要求如下：

• 必须是完整的 URL；
• 不能以/结尾，例如https://github.tooljet.com；
• 如果使用 GitHub 公有云，该字段留空即可。

Host Name 的作用体现在 git-oauth.service.ts：它同时决定了授权端点、用户信息端点与邮箱端点的基础地址。以https://github.tooljet.com为例，换取令牌的地址为https://github.tooljet.com/login/oauth/access_token，用户信息接口为https://github.tooljet.com/api/v3/user，这与 GitHub Enterprise 的 REST API 路径约定一致。

六、保存并验证登录入口

点击Save changes保存配置后，GitHub 登录按钮就会出现在 ToolJet 的登录页面上。随后：

1. 从 SSO 页面的General Settings（通用设置）中获取Login URL，该地址可直接用于引导用户通过 GitHub SSO 登录；
2. 使用无痕窗口或退出登录状态访问该 Login URL，验证能否通过 GitHub 授权并成功进入工作区。

七、通过环境变量将 GitHub 设为实例级默认 SSO

除了在界面中逐工作区配置，ToolJet 还支持通过环境变量在实例级别直接启用 GitHub SSO。下表为文档给出的三个变量：

配置后Redirect URL 应为<host>/sso/git，即你的 ToolJet 实例地址加上/sso/git路径。

从源码看，这三个变量在后端有明确的消费逻辑：

• 在 login-configs/util.service.ts 中，constructSSOConfigs会读取SSO_GIT_OAUTH2_CLIENT_ID与SSO_GIT_OAUTH2_HOST来构造对外暴露的gitSSO 配置，其中enabled由!!SSO_GIT_OAUTH2_CLIENT_ID决定——即只要设置了 Client ID，GitHub SSO 即视为启用；
• 在 addInstanceLevelSSOConfigs 中，当检测到SSO_GIT_OAUTH2_CLIENT_ID存在且当前工作区没有git类型配置时，会向该工作区注入一条实例级配置，其中clientSecret通过EncryptionService.encryptColumnValue加密后存储；
• 在 auth/util.service.ts 中，SSO_GIT_OAUTH2_CLIENT_ID、SSO_GIT_OAUTH2_CLIENT_SECRET、SSO_GIT_OAUTH2_HOST会被一并读取用于构造 OAuth 客户端配置。

因此，在docker-compose.yaml或环境文件中加入上述三个变量并重启服务，即可让所有继承实例配置的工作区获得 GitHub 登录能力，适合多工作区场景下统一开启。

八、在应用中使用 ssoUserInfo 访问 GitHub 用户信息

从 ToolJet2.28.0-ee2.12.2版本开始，GitHub SSO 登录后返回的 GitHub 用户信息会被 ToolJet 暴露给前端，存放在currentUser全局变量的ssoUserInfo属性下（关于 Inspector 的详细用法可参考 use-inspector 文档）。

你可以在应用任意位置用 JavaScript 表达式动态访问这些信息：

{{globals.currentUser.ssoUserInfo.<key>}}

8.1 源码侧的数据流转

这条数据链路在后端与前端均有明确实现：

• 后端在 session/util.service.ts 中将会话中的userDetails?.ssoUserInfo取出并挂到当前会话对象上；
• 前端在 useAppData.js 中把会话中的current_user.sso_user_info映射进应用数据上下文，从而支持{{globals.currentUser.ssoUserInfo.xxx}}的求值语法；
• 此外前端还有专门的 refreshSsoInfo.js，用于在令牌刷新后将最新的sso_user_info同步进应用状态，保证应用中读取到的用户信息不会过期。

也就是说，ssoUserInfo并非静态快照，而是与会话令牌联动、可被后端刷新同步的动态数据。

8.2 GitHub 返回的完整用户信息字段

GitHub 用户接口返回的字段及其在 ToolJet 中的访问语法如下：

安全提醒：access_token是登录用户的敏感凭据。上表中的字段可以在 ToolJet 前端表达式中访问，因此在构建应用时应避免将包含access_token的数据写入日志、审计表或暴露给非授权用户查看的界面。

九、实战示例：用 access_token 调用 GitHub API 获取粉丝列表

access_token最常见的用途是代表当前用户调用 GitHub API。下面以“获取登录用户的粉丝列表”为例演示完整流程：

1. 登录：使用 GitHub SSO 完成 ToolJet 登录（前置步骤见上文第二至六节）。

2. 新建查询：在 ToolJet 应用中新建一个REST API查询，方法选择GET，URL 填写：

   https://api.github.com/user/followers

   该接口返回当前认证用户（即登录用户）的粉丝列表。

3. 设置请求头：在查询的 Headers 区域添加一个键值对：

   • key：Authorization
   • value：Bearer {{globals.currentUser.ssoUserInfo.access_token}}

   这里通过双花括号表达式把当前登录用户的 GitHub access token 作为 Bearer 令牌注入请求头，从而让 GitHub API 识别出“以该用户身份发起请求”。

4. 执行查询：运行查询后，响应体中即为该登录用户的粉丝列表。若令牌有效且用户有粉丝，你将看到包含粉丝login、id、avatar_url等字段的数组。

同样的思路可以扩展到 GitHub API 的其他端点，例如https://api.github.com/user/repos拉取仓库列表、https://api.github.com/user拉取用户详情等。凡是需要“以登录用户身份”调用的 GitHub 接口，都可以复用{{globals.currentUser.ssoUserInfo.access_token}}这个动态令牌。需要注意的是，该令牌的权限范围取决于你在 GitHub OAuth App 中申请的 scope；若应用需要读取私有仓库或写入操作，需要在 GitHub OAuth App 中配置相应的权限范围。

十、常见问题排查要点

• 回调地址不匹配：GitHub OAuth App 中填写的 Authorization callback URL 必须与 ToolJet 生成的 Redirect URL（<host>/sso/git）完全一致，包括协议与域名；不一致时 GitHub 会拒绝回调。
• 登录后邮箱为空：GitHub 允许用户隐藏邮箱，ToolJet 后端会通过/user/emails接口兜底查找 primary 邮箱（见 git-oauth.service.ts）；若仍未取到，请检查 GitHub 账号的邮箱可见性设置。
• Host Name 格式错误：自托管 GitHub Enterprise 的 Host Name 必须以 URL 形式填写且不能以/结尾，否则会导致请求端点拼接错误。
• 环境变量未生效：实例级默认 SSO 由SSO_GIT_OAUTH2_CLIENT_ID驱动（login-configs/util.service.ts），确认环境变量已正确注入并重启服务后再验证登录。

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet