ToolJet 自动 SSO 登录Automatic SSO Login配置指南让用户跳过登录页直达工作区【免费下载链接】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 自动 SSO 登录Automatic SSO Login功能的配置与原理指南。该功能允许在满足特定前置条件的工作区中让已配置好 SSO 的用户绕过登录页面直接进入 ToolJet 应用常用于企业内网、团队门户等追求零摩擦登录体验的场景。读完本文你将掌握该功能的启用条件、环境变量与 UI 两种配置路径、底层触发判定逻辑含源码佐证以及常见配置错误的排查思路。功能概述什么是自动 SSO 登录在默认情况下用户访问 ToolJet 时首先会看到登录页面需要选择密码登录或某个 SSO 提供方Google、GitHub、LDAP、SAML、OIDC 等完成认证。而开启自动 SSO 登录后只要当前工作区满足以下两个前置条件ToolJet 就会在用户到达登录页时直接发起对应的 SSO 认证流程不再显示登录表单工作区只启用了唯一一个 SSO 方法密码登录form 登录已被禁用。该功能对应的官方文档位于 docs/versioned_docs/version-2.50.0-LTS/user-authentication/sso/auto-sso-login.md并标记为Paid feature付费功能启用前请确认当前许可证包含该能力。从源码结构看该开关在实例instance与工作区workspace两个层级均有落点实例级配置项AUTOMATIC_SSO_LOGIN定义于 server/src/modules/instance-settings/constants/index.ts而工作区级开关automaticSsoLogin由组织设置写入数据库。下文会分别说明两种配置路径。配置方式一通过环境变量启用官方文档路径这是 2.50.0-LTS 文档给出的标准配置方式操作步骤如下确保工作区只启用一个 SSO 方法Google、GitHub、LDAP、SAML、OIDC 中仅保留一个为 enabled 状态禁用工作区的密码登录在 ToolJet 服务端的环境变量中加入以下变量该变量的完整说明位于 docs/versioned_docs/version-2.50.0-LTS/setup/env-vars.md 的 SSO Configurations 小节SSO_SKIP_LOGIN_SCREEN true在 env-vars.md 中该变量被收录进 SSO Configurations (Optional) 表格原文说明为环境变量说明SSO_SKIP_LOGIN_SCREEN设置为true以启用自动 SSO 登录。仅当只配置了一个 SSO 方法且密码登录被禁用时生效修改环境变量后需要重启 ToolJet 服务端进程使配置生效。该变量属于实例级instance-level配置一旦开启会影响整个实例上所有满足条件的工作区。配套的 SSO 环境变量速查自动 SSO 登录依赖底层 SSO 提供方的正确配置下表是 env-vars.md 中与 SSO 相关的完整环境变量列表配置自动登录前请先确保这些变量就位环境变量说明SSO_GOOGLE_OAUTH2_CLIENT_IDGoogle OAuth 客户端 IDSSO_GIT_OAUTH2_CLIENT_IDGitHub OAuth 客户端 IDSSO_GIT_OAUTH2_CLIENT_SECRETGitHub OAuth 客户端密钥SSO_GIT_OAUTH2_HOSTGitHub OAuth 主机名自托管 GitHub 时填写SSO_ACCEPTED_DOMAINS逗号分隔的、支持 SSO 认证的邮箱域名列表SSO_DISABLE_SIGNUPS当认证用户不存在时禁用用户注册SSO_SKIP_LOGIN_SCREEN设为true启用自动 SSO 登录本文核心变量其中SSO_GOOGLE_OAUTH2_CLIENT_ID、SSO_GIT_OAUTH2_CLIENT_ID、SSO_GIT_OAUTH2_CLIENT_SECRET、SSO_GIT_OAUTH2_HOST也会在服务端读取用于向前端暴露各 SSO 提供方的启用状态可参见 server/src/modules/auth/util.service.ts。配置方式二通过实例设置与工作区登录设置界面源码确认在较新版本的仓库中自动 SSO 登录不再局限于环境变量还提供了两处 UI 配置入口以下内容基于当前仓库源码确认具体入口名称以所部署版本的界面为准。实例级配置项AUTOMATIC_SSO_LOGIN服务端把自动 SSO 登录建模为一条实例系统设置system 类型、boolean 数据类型枚举定义INSTANCE_SYSTEM_SETTINGS.AUTOMATIC_SSO_LOGIN AUTOMATIC_SSO_LOGIN见 server/src/modules/instance-settings/constants/index.ts默认值与说明数据迁移 server/data-migrations/1723636080272-AddAutomaticSSOLoginInInstanceSettings.ts 在升级时为所有实例插入默认值false其 helperText 为This will simulate the configured SSO login, bypassing the login screen in ToolJet即模拟已配置的 SSO 登录绕过 ToolJet 登录页暴露给前端实例配置服务会在fetchDefaultInstanceConfig()中把该键加入需要下发到前端的配置白名单见 server/src/modules/configs/service.ts。前端通过window.public_config.AUTOMATIC_SSO_LOGIN true读取它。工作区级开关automaticSsoLogin工作区登录设置页 frontend/src/modules/WorkspaceSettings/pages/WorkspaceLogin/WorkspaceLoginSettings.jsx 中有一个 Automatic SSO Login 开关开启后调用organizationService.editOrganization({ automaticSsoLogin: true })写入组织配置该页面第 329 行附近为开启逻辑第 138、362 行为关闭逻辑。页面加载时从组织设置读取automatic_sso_login字段见该文件第 227 行作为开关初值。两级配置的优先级关系前端登录页的判定逻辑明确区分了这两个层级见 frontend/src/modules/auth/pages/AppLoginPage/AppLoginPage.jsx// Auto-SSO: if exactly one SSO is enabled, no form login, and auto-SSO is on → trigger it const shouldAttemptAutoSSO window.public_config?.ENABLE_WORKSPACE_LOGIN_CONFIGURATION true ? configs?.automatic_sso_login // 工作区级开关组织配置 : window.public_config?.AUTOMATIC_SSO_LOGIN true; // 实例级开关环境变量/实例设置即当实例开启了工作区登录配置ENABLE_WORKSPACE_LOGIN_CONFIGURATION时以工作区级的automatic_sso_login为准否则回退到实例级的AUTOMATIC_SSO_LOGIN也就是通过SSO_SKIP_LOGIN_SCREENtrue环境变量驱动的实例设置。这也解释了为什么 2.50.0-LTS 文档只要求设置环境变量——在未开放工作区级登录配置的版本中实例级开关是唯一的控制点。登录页触发链路与判定源码解析自动 SSO 登录的核心判定发生在应用登录页App Login Page加载时完整链路如下用户访问某个应用的登录页前端解析出目标应用及其organizationId通过loginConfigsService.getOrganizationConfigs(organizationId)拉取该工作区的全部 SSO 配置Google、Git、LDAP、SAML、OIDC、form见 AppLoginPage.jsx按上文的两级优先级判定shouldAttemptAutoSSO统计启用中的 SSO 数量见 AppLoginPage.jsxconst hasEnabledOidc Array.isArray(configs?.openid) ? configs.openid.some((c) c.enabled) : configs?.openid?.enabled; const enabledSSOs [ configs?.google?.enabled, configs?.git?.enabled, configs?.ldap?.enabled, configs?.saml?.enabled, hasEnabledOidc, ].filter(Boolean); if (enabledSSOs.length 1 !configs?.form?.enabled) { // 命中条件恰好一个 SSO 启用 且 form密码登录未启用 authenticationService.saveLoginOrganizationId(config.organizationId); setCookie(redirectPath, appRedirectPath, iframe); setSsoTriggered(true); }命中条件后页面不再渲染登录表单而是直接渲染SSOAuthModule并自动发起该 SSO 提供方的认证见 AppLoginPage.jsx。这里有两个值得注意的实现细节redirectPathCookie触发自动 SSO 前会把目标应用的跳转路径写入 CookieSSO 回调完成后据此回到原始应用页面。源码注释特别说明这里不能复用setRedirectUrlToCookie()因为此时appConfig状态尚未更新完毕只能手动saveLoginOrganizationIdsetCookie见 AppLoginPage.jsx公共应用Public app优先如果目标应用是公共应用且非本地预览会直接跳转到应用本身不走 SSO 判定逻辑见 AppLoginPage.jsx。条件不满足时的自动保护机制自动 SSO 登录有一个容易踩坑的点它不是一个开了就生效的开关而是强依赖前置条件。前端在设置页做了对应的保护见 WorkspaceLoginSettings.jsx// 统计启用的 SSO排除 form 密码登录与无权限访问的受保护 SSO const enabledSSOs combinedSSOConfigs.filter( (obj) obj.enabled obj.sso ! form (!this.protectedSSO.includes(obj.sso) || this.state.featureAccess?.[obj.sso]) ); // 仅当密码登录被禁用且恰好启用一个 SSO 时才允许打开自动 SSO 开关 const canToggleAutomaticSSOLogin !this.state.options.passwordLoginEnabled enabledSSOs.length 1; if (!canToggleAutomaticSSOLogin) { updatedOptions.automaticSsoLogin false; // 条件不满足则强制关闭 // 并同步调用后端关闭组织配置 await organizationService.editOrganization({ automaticSsoLogin: false }); }对应地登录页在enabledSSOs.length 1 !configs?.form?.enabled不成立时不会触发自动登录用户仍会看到正常登录表单不会被卡死。此外若用户在启用自动 SSO 后又重新打开了密码登录开关前端会弹出确认弹窗showDisableAutoSSOModal并同步将automaticSsoLogin置为false见 WorkspaceLoginSettings.jsx。常见配置问题与排查建议结合上文的前置条件与源码判定逻辑可以总结出以下排查清单现象可能原因排查方向设置了SSO_SKIP_LOGIN_SCREENtrue但仍显示登录页实例启用了工作区级登录配置ENABLE_WORKSPACE_LOGIN_CONFIGURATIONtrue自动登录改由工作区开关控制在对应工作区的登录设置中开启 Automatic SSO Login工作区自动 SSO 开关无法打开/被强制关闭密码登录未禁用或启用的 SSO 数量不等于 1包含 OIDC 的多条配置也计入确认只保留一个 SSO 方法并禁用 form 密码登录勾选后自动登录未触发环境变量/实例设置未被前端读到确认服务端已重启且AUTOMATIC_SSO_LOGIN出现在下发的 public config 中可检查window.public_config.AUTOMATIC_SSO_LOGIN的值认证成功但未回到目标应用redirectPathCookie 在 iframe 场景下未正确写入确认前端代码按window ! window.top区分 iframe 与非 iframe 场景写入 CookieAppLoginPage.jsx小结自动 SSO 登录是 ToolJet 面向单一 SSO 提供方工作区提供的零点击登录能力其配置要点可概括为三句话只保留一个 SSO 方法、禁用密码登录、然后通过环境变量SSO_SKIP_LOGIN_SCREENtrue或实例/工作区设置中的 Automatic SSO Login 开关开启。底层实现上前端登录页会在加载时动态统计启用的 SSO 数量并校验 form 登录状态条件命中后自动渲染SSOAuthModule完成认证跳转条件不满足时则自动回退到标准登录页确保任何配置组合下用户都不会被锁定在登录流程之外。更多 SSO 提供方的详细配置方法可继续查阅 docs/versioned_docs/version-2.50.0-LTS/user-authentication/sso 目录下的对应文档。【免费下载链接】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），仅供参考