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

ToolJet 配置 GitHub 单点登录SSOOAuth 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/ToolJetToolJet 内置了对 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回调 ToolJetToolJet 后端用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登录 ToolJet 控制台点击左侧边栏底部的Settings⚙️进入Workspace Settings。在Workspace Settings的侧边栏中选择Workspace login。右侧会列出多种 SSO 客户端的开关所有开关默认关闭。找到GitHub对应的开关并打开会弹出包含 Host name、Client ID、Client secret 等输入项的配置弹窗。弹窗左上角有一个启用开关将其打开后先不填写任何参数直接点击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打开 GitHub 的Developer settings进入OAuth Apps页面点击New OAuth App创建新的 OAuth App。依次填写以下字段App Name应用名称例如ToolJetHomepage URLToolJet 实例的首页地址Authorization callback URL必须填写上一步在 ToolJet 中生成的Redirect URL即host/sso/git这是 GitHub 授权后回调的地址填错会导致登录失败。点击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 的登录页面上。随后从 SSO 页面的General Settings通用设置中获取Login URL该地址可直接用于引导用户通过 GitHub SSO 登录使用无痕窗口或退出登录状态访问该 Login URL验证能否通过 GitHub 授权并成功进入工作区。七、通过环境变量将 GitHub 设为实例级默认 SSO除了在界面中逐工作区配置ToolJet 还支持通过环境变量在实例级别直接启用 GitHub SSO。下表为文档给出的三个变量变量说明SSO_GIT_OAUTH2_CLIENT_IDGitHub OAuth 客户端 IDSSO_GIT_OAUTH2_CLIENT_SECRETGitHub OAuth 客户端密钥SSO_GIT_OAUTH2_HOST自托管 GitHub 时的 OAuth Host 名称配置后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 IDGitHub 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 中的访问语法如下Key说明访问语法loginGitHub 用户名{{globals.currentUser.ssoUserInfo.login}}idGitHub 用户 ID{{globals.currentUser.ssoUserInfo.id}}node_idGitHub 用户节点 ID{{globals.currentUser.ssoUserInfo.node_id}}avatar_urlGitHub 用户头像 URL{{globals.currentUser.ssoUserInfo.avatar_url}}gravatar_idGitHub 用户 Gravatar ID{{globals.currentUser.ssoUserInfo.gravatar_id}}urlGitHub 用户 URL{{globals.currentUser.ssoUserInfo.url}}html_urlGitHub 用户 HTML URL{{globals.currentUser.ssoUserInfo.html_url}}followers_urlGitHub 用户粉丝列表 URL{{globals.currentUser.ssoUserInfo.followers_url}}following_urlGitHub 用户关注列表 URL{{globals.currentUser.ssoUserInfo.following_url}}gists_urlGitHub 用户 Gist URL{{globals.currentUser.ssoUserInfo.gists_url}}starred_urlGitHub 用户 Starred URL{{globals.currentUser.ssoUserInfo.starred_url}}subscriptions_urlGitHub 用户订阅 URL{{globals.currentUser.ssoUserInfo.subscriptions_url}}organizations_urlGitHub 用户组织 URL{{globals.currentUser.ssoUserInfo.organizations_url}}repos_urlGitHub 用户仓库 URL{{globals.currentUser.ssoUserInfo.repos_url}}events_urlGitHub 用户事件 URL{{globals.currentUser.ssoUserInfo.events_url}}received_events_urlGitHub 用户接收事件 URL{{globals.currentUser.ssoUserInfo.received_events_url}}typeGitHub 用户类型{{globals.currentUser.ssoUserInfo.type}}site_admin是否为 GitHub 站点管理员{{globals.currentUser.ssoUserInfo.site_admin}}nameGitHub 用户姓名{{globals.currentUser.ssoUserInfo.name}}companyGitHub 用户公司{{globals.currentUser.ssoUserInfo.company}}blogGitHub 用户博客{{globals.currentUser.ssoUserInfo.blog}}locationGitHub 用户所在地{{globals.currentUser.ssoUserInfo.location}}emailGitHub 用户邮箱{{globals.currentUser.ssoUserInfo.email}}hireable是否可被雇佣{{globals.currentUser.ssoUserInfo.hireable}}bioGitHub 用户简介{{globals.currentUser.ssoUserInfo.bio}}twitter_usernameGitHub 用户 Twitter 用户名{{globals.currentUser.ssoUserInfo.twitter_username}}public_repos公开仓库数{{globals.currentUser.ssoUserInfo.public_repos}}public_gists公开 Gist 数{{globals.currentUser.ssoUserInfo.public_gists}}followers粉丝数{{globals.currentUser.ssoUserInfo.followers}}following关注数{{globals.currentUser.ssoUserInfo.following}}created_at账号创建时间{{globals.currentUser.ssoUserInfo.created_at}}updated_at账号更新时间{{globals.currentUser.ssoUserInfo.updated_at}}access_tokenGitHub 用户访问令牌登录用户的敏感信息{{globals.currentUser.ssoUserInfo.access_token}}安全提醒access_token是登录用户的敏感凭据。上表中的字段可以在 ToolJet 前端表达式中访问因此在构建应用时应避免将包含access_token的数据写入日志、审计表或暴露给非授权用户查看的界面。九、实战示例用 access_token 调用 GitHub API 获取粉丝列表access_token最常见的用途是代表当前用户调用 GitHub API。下面以“获取登录用户的粉丝列表”为例演示完整流程登录使用 GitHub SSO 完成 ToolJet 登录前置步骤见上文第二至六节。新建查询在 ToolJet 应用中新建一个REST API查询方法选择GETURL 填写https://api.github.com/user/followers该接口返回当前认证用户即登录用户的粉丝列表。设置请求头在查询的 Headers 区域添加一个键值对keyAuthorizationvalueBearer {{globals.currentUser.ssoUserInfo.access_token}}这里通过双花括号表达式把当前登录用户的 GitHub access token 作为 Bearer 令牌注入请求头从而让 GitHub API 识别出“以该用户身份发起请求”。执行查询运行查询后响应体中即为该登录用户的粉丝列表。若令牌有效且用户有粉丝你将看到包含粉丝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 URLhost/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考