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 adminWorkspace 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设置面板所有改动即时保存到后端登录配置接口。SSOSingle Sign-On配置SSO 让组织能够集中管理用户访问用户可以使用同一套凭据登录不同的工具管理员也可以在需要时快速授予或撤销访问权限从而显著改善组织的 onboarding 与 offboarding 体验。在实例级别可以配置的 SSO 类型包括GoogleGitHubOpenID Connect详细的 SSO 配置指南请参考 SSO 文档。通过环境变量配置 Google / GitHub SSO除了在 UI 中配置外ToolJet 还支持直接用环境变量把 Google 或 GitHub 设置为默认 SSO。将 Google 设为默认 SSO 所需的环境变量变量说明SSO_GOOGLE_OAUTH2_CLIENT_IDGoogle OAuth 客户端 ID将 GitHub 设为默认 SSO 所需的环境变量变量说明SSO_GIT_OAUTH2_CLIENT_IDGitHub OAuth 客户端 IDSSO_GIT_OAUTH2_CLIENT_SECRETGitHub 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 自托管主机名。当某个工作区开启了继承实例级 SSOinheritSSO时addInstanceLevelSSOConfigs方法util.service.ts会将这些环境变量中的配置以sso: google或sso: git的形式注入到该工作区的 SSO 配置列表中其中 GitHub 的clientSecret会先经过加密服务EncryptionService.encryptColumnValue再存入配置。getInstanceSSOConfigsservice.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可关闭密码重试限制falsePASSWORD_RETRY_LIMIT允许的最大重试次数超过后禁用认证5Enable 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 直接操作也可通过环境变量在部署阶段声明式生效两者结合即可构建一套完整、可控、可审计的自托管实例认证体系。【免费下载链接】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），仅供参考