ToolJet 自托管部署中的 Workspace Login：工作区级认证配置完整指南

ToolJet 自托管部署中的 Workspace 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 自托管self-hosted部署中登录认证既可以在**实例级Instance Level统一配置也可以下放到工作区级Workspace Level**进行差异化覆盖。本文聚焦工作区级认证配置涵盖 SSOGoogle、GitHub、OpenID Connect、LDAP、SAML、Allowed Domains 域名白名单、免邀请注册Sign-Up Without Invitations、密码登录及其重试限制PASSWORD_RETRY_LIMIT/DISABLE_PASSWORD_RETRY_LIMIT和 Automatic SSO Login 等核心能力。读完本文你将掌握如何在 ToolJet 中按工作区定制登录策略并结合源码理解每个配置项的底层实现逻辑。两级认证模型Instance Level 与 Workspace Level在 ToolJet 自托管环境中认证配置可以在两个层级生效Instance Level实例级对所有工作区全局生效仅超级管理员super admin可配置Workspace Level工作区级对指定工作区覆盖实例级配置超级管理员与工作区管理员均可配置。工作区级配置之所以存在是为了满足同一实例下不同部门/客户拥有各自独立登录策略的场景。例如一个服务型公司为多个客户分别创建工作区就可以为每个客户工作区配置不同的 SSO 提供商甚至混用 SSO 与邮箱密码登录而互不干扰。更详细的场景化说明可参考 认证总览文档 与 实例级登录文档。进入 Workspace Login 配置页配置工作区级认证的入口路径为登录 ToolJet 后进入目标工作区打开Workspace SettingsWorkspace login典型访问 URL 形如https://app.corp.com/nexus/workspace-settings/workspace-login其中nexus为工作区 slug。在该页面可以集中管理 SSO、Allowed Domains、免邀请注册、密码登录与自动 SSO 登录等设置。SSOSingle Sign-OnSSO 的价值在于让组织统一管理用户访问用户用同一套凭据登录多个工具管理员也能在入职/离职时快速授予或回收访问权限从而改善组织的 onboarding 与 offboarding 体验。工作区级 SSO 有两种模式Instance SSO继承实例 SSO打开Instance SSO开关让当前工作区直接继承实例级已配置的 SSO 提供商适用于希望统一认证口径的工作区Workspace SSO工作区独立配置在工作区级独立配置 Google、GitHub、OpenID Connect、LDAP 或 SAML适用于需要差异化认证的客户/部门工作区。从源码看该开关对应inheritSSO布尔字段与automaticSsoLogin、enableSignUp等字段一并定义在 server/src/modules/login-configs/dto/index.ts 的OrganizationConfigsUpdateDto中服务端通过这些字段持久化每个工作区的独立登录配置。SSO 的完整配置步骤如各提供商的 Client ID / Secret 申请、回调地址等请参考 SSO 文档。Allowed Domains按邮箱域名限制登录Allowed Domains用于将登录与注册限制在指定邮箱域名内确保只有组织内授权用户能够注册或登录。支持通过逗号分隔一次配置多个允许域名例如corp.com、corp.io、corp.ai未命中白名单的邮箱域名将无法注册/登录从而降低外部账号进入工作区的风险。源码层面工作区配置的OrganizationConfigsUpdateDto接受domain、passwordAllowedDomains、passwordRestrictedDomains等字段均通过sanitizeInput做输入清洗并限制最大长度 250 字符服务端会据此在登录流程中校验用户邮箱域名是否被允许。Sign-Up Without Invitations免邀请自助注册Enable Signup允许用户不经过邀请直接注册并加入工作区简化组织 onboarding 流程开启后新注册用户会以该工作区的End User终端用户角色自动加入工作区管理员可在用户完成 onboarding 后随时将其角色调整为其他角色如 Builder、Admin角色体系详见 用户角色文档需要特别注意的是工作区级免邀请注册的可用性依赖实例级设置。若实例级配置未开启 Personal Workspace 选项或工作区级注册开关被关闭则自助注册行为会有所不同——实例级开启时新用户会自动获得个人工作区并成为其管理员。两种层级的差异详见 自助注册文档。Password Login密码登录与重试限制Password Login允许用户使用邮箱 密码登录。对于安全要求更高的组织可以改用 SSO 获得更好的安全性与管控能力。页面上的开关可启用/禁用登录页的密码登录务必在 SSO 已正确配置的前提下再关闭密码登录否则你将因无法登录而被锁在系统之外。为防止暴力破解密码认证在连续失败达到一定次数后会被禁用相关行为由两个环境变量控制变量说明默认值DISABLE_PASSWORD_RETRY_LIMIT设为true时禁用密码重试次数限制功能falsePASSWORD_RETRY_LIMIT密码认证被禁用前允许的最大重试次数5源码视角重试限制如何生效在 server/src/modules/auth/util.service.ts 的validateLoginUser方法中可以清晰看到该机制的完整实现首先通过邮箱在指定工作区内查找用户并校验用户状态ACTIVE/ARCHIVED与账号是否被禁用读取PASSWORD_RETRY_LIMIT环境变量const passwordRetryConfig this.configService.getstring(PASSWORD_RETRY_LIMIT);未配置时默认回退为5当DISABLE_PASSWORD_RETRY_LIMIT ! true且user.passwordRetryCount passwordRetryAllowed时直接抛出UnauthorizedException提示已达到最大密码重试次数请使用忘记密码功能重置密码比对失败时passwordRetryCount会 1 并持久化从而累计失败次数只有密码校验通过的用户才能完成登录。这意味着默认情况下用户连续输错 5 次密码后其账号的密码认证将被锁定直到通过忘记密码流程重置。需要放宽或收紧该策略时分别调整PASSWORD_RETRY_LIMIT与DISABLE_PASSWORD_RETRY_LIMIT两个环境变量即可。Automatic SSO Login绕过登录页直接认证Automatic SSO Login允许用户完全跳过登录页交互被直接重定向到已配置的 SSO 提供商完成认证从而简化登录体验。启用该功能的两个前提条件密码登录必须处于禁用状态即关闭 Password Login 开关实例/工作区中只配置了唯一一个 SSO 提供商。满足上述条件后用户访问工作区时会被自动导向唯一的 SSO 提供商进行认证无需手动选择登录方式。该开关在工作区配置 DTO 中对应automaticSsoLogin布尔字段服务端会结合 SSO 配置与密码登录开关共同决定登录页的最终行为。配置建议与注意事项明确继承还是覆盖工作区默认可以继承实例级 SSO打开 Instance SSO 开关。若某工作区需要独立认证再关闭继承并配置工作区级 SSO域名白名单配合免邀请注册Allowed Domains 与 Enable Signup 组合使用可实现仅限公司邮箱自助注册的合规 onboarding 流程关闭密码登录前先验证 SSO避免因 SSO 未生效导致全员无法登录重试策略按需调优安全敏感场景可调低PASSWORD_RETRY_LIMIT内部低风险场景可设置DISABLE_PASSWORD_RETRY_LIMITtrue关闭限制自动 SSO 登录的严格前提只有同时满足密码登录关闭 单一 SSO 提供商时才会生效多提供商或开启密码登录时该功能不会触发。通过工作区级登录配置ToolJet 自托管实例可以在保持全局统一认证的基础上为不同工作区提供差异化的 SSO、域名限制与注册策略——从源码实现登录配置 DTO、密码重试校验到 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），仅供参考