ToolJet 自托管实例级登录配置完全指南：Instance Login 的 SSO、域名白名单与安全策略详解-创锋一号

ToolJet 自托管实例级登录配置完全指南：Instance Login 的 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

本指南聚焦于 ToolJet 自托管部署中的Instance Level（实例级）登录配置，覆盖 SSO 单点登录、允许登录域名、无邀请注册、密码登录开关、自动 SSO 登录与自定义登出 URL 等核心能力。读者完成本文学习后，将能够以超级管理员身份进入实例设置，为整个实例的所有工作区统一配置认证策略，并能结合环境变量与底层源码理解每项配置的生效机制。

两级登录配置架构：Instance Level 与 Workspace Level

在自托管部署中，ToolJet 的认证配置存在两个层级，这一点决定了管理员在配置前必须先明确作用域：

层级	作用范围	可配置者
Instance Level（实例级）	全局生效，应用于实例内所有工作区	仅超级管理员（super admin）
Workspace Level（工作区级）	覆盖特定工作区的实例级设置	超级管理员与工作区管理员

本文聚焦实例级配置；工作区级配置的详细说明可参考 workspace-login.md。两级配置的完整场景（纯实例级、纯工作区级、混合配置）可阅读 overview.md。

从源码结构看，两种层级的配置共享同一套 SSO 配置实体（SSOConfigs），通过configScope字段区分作用域。在 login-configs/service.ts 中，工作区级配置写入时使用ConfigScope.ORGANIZATION，而实例级配置则通过环境变量注入，两者在读取时会被合并处理。

进入实例登录配置页面

实例级登录配置入口位于Settings > Instance login，对应示例 URL 为：

https://app.corp.com/instance-settings/instance-login

打开该页面后，可以配置以下设置：

该页面由前端路由instance-login承载（见 frontend/src/_helpers/routes.js），渲染的是Instance login设置面板，所有改动即时保存到后端登录配置接口。

SSO（Single Sign-On）配置

SSO 让组织能够集中管理用户访问：用户可以使用同一套凭据登录不同的工具，管理员也可以在需要时快速授予或撤销访问权限，从而显著改善组织的 onboarding 与 offboarding 体验。

在实例级别，可以配置的 SSO 类型包括：

Google
GitHub
OpenID Connect

详细的 SSO 配置指南请参考 SSO 文档。

通过环境变量配置 Google / GitHub SSO

除了在 UI 中配置外，ToolJet 还支持直接用环境变量把 Google 或 GitHub 设置为默认 SSO。将 Google 设为默认 SSO 所需的环境变量：

变量	说明
`SSO_GOOGLE_OAUTH2_CLIENT_ID`	Google OAuth 客户端 ID

将 GitHub 设为默认 SSO 所需的环境变量：

变量	说明
`SSO_GIT_OAUTH2_CLIENT_ID`	GitHub OAuth 客户端 ID
`SSO_GIT_OAUTH2_CLIENT_SECRET`	GitHub OAuth 客户端密钥
`SSO_GIT_OAUTH2_HOST`	若 GitHub 为自托管实例，填写其 OAuth 主机名

环境变量的底层生效机制

这些环境变量在后端被真实读取并组装成实例级 SSO 配置。在 login-configs/util.service.ts 的constructSSOConfigs方法中：

google.enabled与configs.client_id直接取自SSO_GOOGLE_OAUTH2_CLIENT_ID，只要该变量存在（非空），Google SSO 即被判定为启用；
git.enabled与configs.client_id取自SSO_GIT_OAUTH2_CLIENT_ID，同时读取SSO_GIT_OAUTH2_HOST作为 GitHub 自托管主机名。

当某个工作区开启了继承实例级 SSO（inheritSSO）时，addInstanceLevelSSOConfigs方法（util.service.ts）会将这些环境变量中的配置以sso: 'google'或sso: 'git'的形式注入到该工作区的 SSO 配置列表中，其中 GitHub 的clientSecret会先经过加密服务（EncryptionService.encryptColumnValue）再存入配置。

getInstanceSSOConfigs（service.ts）还补充展示了form（表单登录）配置：enable_sign_up由DISABLE_SIGNUPS环境变量控制——当DISABLE_SIGNUPS !== 'true'时允许注册。

实例级 SSO 的端到端测试

仓库中提供了实例级 OAuth 的端到端测试，可作为配置正确性的验证参考：

oauth-google-instance.spec.ts：验证实例级 Google OAuth 登录流程
oauth-git-instance.spec.ts：验证实例级 GitHub OAuth 登录流程

这两个测试文件位于server/test/modules/auth/e2e/下，覆盖了通过环境变量注入实例级 SSO 后完整的认证链路。

Allowed Domains（允许登录域名）

该功能用于将登录访问限制在特定邮箱域名内，确保只有组织内的授权用户才能注册或登录。

配置方式：在Allowed Domains字段中填写允许登录的域名，多个域名用逗号分隔。例如：

corp.com, corp.io, corp.ai

从数据库迁移记录看，该能力由实例设置表承载——AddAllowedDomainsInInstanceSettings.ts 在实例设置中新增了允许域名列；AddPasswordDomainColumnsToOrganizations.ts 进一步在工作区组织实体上增加了密码登录相关的域名列（passwordAllowedDomains、passwordRestrictedDomains），这些字段在 service.ts 的updateGeneralOrganizationConfigs中被一并持久化。

Sign-Up Without Invitations（无邀请注册）

该功能让组织简化用户 onboarding——用户无需收到邀请即可自行注册账户。

Enable Signup开关用于控制用户能否在未被邀请的情况下创建账户。
该功能仅在Manage Instance 设置中启用了 Personal Workspace（个人工作区）时可用。当用户在该功能开启状态下注册时，系统会自动为其创建一个新的个人工作区，并将该用户设为该工作区的管理员。

更多细节可参考自助注册文档中的 "Enable Sign Up at Instance Level" 章节。后端对应的迁移 AddEnableSignUpInInstanceSettings.ts 与 DisableSignUpIfPersonalWorkspaceNotAllowed.ts 保证了该开关与个人工作区策略的一致性。

Password Login（密码登录）

密码登录允许用户使用邮箱和密码登录。不过，为了更好的安全性和可控性，组织也可以选择使用 SSO。

通过切换开关可以启用或禁用登录页上的密码登录。
注意：只有在 SSO 已正确配置的情况下才应禁用密码登录，否则你将把自己锁在系统之外。

作为纵深防御，工作区级的密码登录还受失败重试次数限制：默认允许5 次重试，可用PASSWORD_RETRY_LIMIT环境变量调整；如需彻底关闭该限制，可将DISABLE_PASSWORD_RETRY_LIMIT设为true（详见 workspace-login.md）：

变量	说明	默认值
`DISABLE_PASSWORD_RETRY_LIMIT`	设为`true`可关闭密码重试限制	`false`
`PASSWORD_RETRY_LIMIT`	允许的最大重试次数，超过后禁用认证	`5`

Enable Workspace Login Configuration（启用工作区登录配置）

该功能允许工作区管理员为各自的工作区定制登录设置，适用于同一实例内不同工作区需要不同登录配置的场景。

开启后，工作区特定的设置将覆盖这些工作区的实例级配置。
对应后端行为体现在updateInheritSSO方法（service.ts）中：通过更新组织的inheritSSO布尔字段，控制该工作区是继承实例级 SSO 还是使用自己的配置。

Automatic SSO Login（自动 SSO 登录）

该功能让用户无需与登录页交互，直接通过已配置的 SSO 提供方完成认证。

启用Automatic SSO Login需要同时满足两个前置条件：

密码登录已禁用；
只配置了一个 SSO 提供方。

后端强制校验逻辑

该前置条件并非仅靠前端提示，后端在保存配置时会进行强校验。在 service.ts 的updateGeneralOrganizationConfigs中，当automaticSsoLogin === true时，系统会遍历该组织的全部 SSO 配置：

统计启用的非表单 SSO 数量（enabledSSOCount）；
检查表单（密码）登录是否已禁用（isFormLoginDisabled）；
若!(isFormLoginDisabled && enabledSSOCount == 1)成立，则直接抛出错误："Automatic SSO login can only be enabled if password login is disabled and there is one SSO enabled"。

前端对应的启用弹窗组件位于 frontend/src/_components/EnableAutomaticSSOLoginModal.jsx，负责引导管理员完成这两个前置条件的检查与确认。

Custom Logout URL（自定义登出 URL）

自定义登出 URL 允许组织在用户登出后将用户重定向到指定页面，例如公司门户或反馈表单。

配置方式：在Custom Logout URL字段中输入目标登出地址即可。对应的数据库迁移 AddCustomLogoutUrl.ts 为该能力新增了存储字段。

配置优先级与安全建议总结

先规划层级：全局统一认证选实例级；部门/客户隔离认证选工作区级；混合场景开启 "Enable Workspace Login Configuration" 后按工作区覆盖。
SSO 优先：能走 SSO 就不依赖密码，利用环境变量（SSO_GOOGLE_OAUTH2_CLIENT_ID等）可在部署阶段即固化默认 SSO。
锁门顺序：禁用密码登录前，务必先确认 SSO 已启用且可正常工作；启用自动 SSO 登录前，确认密码登录已禁用且仅存在一个 SSO 提供方。
域名收敛：通过 Allowed Domains 限定注册/登录的邮箱域名，减少外部账号渗透面。
登出闭环：使用 Custom Logout URL 把用户引回组织门户或反馈页，完善安全审计与用户体验链路。

以上配置全部可通过 UI 直接操作，也可通过环境变量在部署阶段声明式生效，两者结合即可构建一套完整、可控、可审计的自托管实例认证体系。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析