ToolJet LDAP 单点登录SSO配置指南从 Workspace 设置到登录验证全流程【免费下载链接】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/ToolJetLDAPLightweight Directory Access Protocol轻量目录访问协议是许多企业内部最常用的用户目录服务ToolJet 支持将 LDAP 直接作为单点登录SSO来源让用户使用 LDAP 账号免密进入指定工作区。本文以 ToolJet 2.50.0-LTS 文档为骨架完整讲解从 Workspace Settings 开启 LDAP、填写连接参数、配置 SSL 证书、生成登录链接到首次登录行为用户组自动同步、头像同步、邀请页跳转的全部细节并结合仓库源码如 sso_config.entity.ts 与 oauth/service.ts说明底层实现原理。一、前置认知ToolJet 中的 LDAP 支持范围在动手配置前需要先明确 ToolJet 对 LDAP 的两个关键限制这也是官方文档明确指出的LDAP 登录仅在 Workspace工作区级别生效不支持 Instance实例级别。也就是说用户通过 LDAP 登录后只会进入所选的特定工作区而不是整个实例LDAP 配置属于工作区维度的 SSO 配置。从源码看ToolJet 的 SSO 配置统一存放在sso_configs表中sso_config.entity.ts其中configScope字段区分organization与instance两种范围而sso枚举SSOType中明确包含LDAP ldap这一类型sso_config.entity.ts。从 sso_config.entity.ts 可以看到 LDAP 配置在数据结构中的完整形态本文后续所有配置字段都与之对应type LDAP { name: string; host: string; port: number; ssl: boolean; sslOptions: { clientKey: string; clientCert: string; serverCert: string; }; basedn: string; basedns?: string[]; bindAttribute?: cn | upn; enableGroupSync: boolean; };二、开启 LDAP 登录从 Workspace Settings 入口开始配置入口位于 ToolJet 工作区管理界面具体操作如下访问 ToolJet Dashboard点击左侧边栏顶部的 ⚙️齿轮图标打开Workspace Settings。在 Workspace Settings 中找到Workspace login区域选择LDAP标签页。默认情况下LDAP 登录开关处于disabled关闭状态。三、填写 LDAP 连接参数与 SSL 配置点击开关将 LDAP 登录enable启用随后会展开配置表单需要填写以下字段配置项说明Name该 SSO 的名称例如Company LDAP。它会被展示在登录页的 “Sign in withName” 按钮上也会出现在 Login URL 中HostnameLDAP 服务器的主机名或 IP 地址对应源码中的host字段PortLDAP 服务器的端口号对应源码中的port字段。常规 LDAP 使用 389LDAPS 使用 636具体以你的目录服务实际监听端口为准Base DN基础区分名Base Distinguished Name即 LDAP 目录树中搜索用户信息的根节点例如dcexample,dccom对应源码中的basedn字段SSL开启后可以选择 SSL 类型None或Certificates。选择 Certificates 时需额外提供Client Key客户端密钥、Client Certificate客户端证书与Server Certificate服务器证书从源码结构看上述字段最终以 JSON 形式保存在sso_configs.configs列中ssl为布尔开关sslOptions中则对应存放clientKey、clientCert、serverCert三份证书材料sso_config.entity.ts。此外数据结构中还预留了bindAttribute支持cn或upn与enableGroupSync等字段与登录后行为相关详见下文第五、六节。配置完成后点击页面底部的Save Changes按钮保存。四、获取并分发 Login URL保存配置后回到Workspace login页面可以复制到 ToolJet 生成的Login URL。该 URL 可直接用于访问工作区登录页用户在此页面点击 “Sign in withLDAP Name” 按钮并输入 LDAP 用户名与密码即可完成登录。URL 页面上还有一个Enable Signups允许自助注册开关其行为逻辑是开启时通过 SSO 认证后系统会检查用户是否已存在于工作区——如果存在用户可以无缝登录如果不存在则按流程创建/邀请用户允许未被邀请的用户通过 SSO 认证进入关闭时只有已被邀请的用户才能在 SSO 认证成功后登录未受邀用户会收到错误提示。对应到源码工作区登录分支的逻辑位于 oauth/service.ts先按邮箱查询工作区用户状态为 ACTIVE 或 INVITED用户存在则直接走登录/激活流程用户不存在且enableSignUp为真时通过findOrCreateUser创建用户否则抛出User does not exist in the workspace异常。可见 “Enable Signups” 开关直接决定了 SSO 认证后新用户的去留。五、首次登录用户组同步与头像同步首次通过 LDAP 登录时ToolJet 会执行额外的检查与同步操作这是官方文档明确强调的行为用户组自动同步ToolJet 会校验 LDAP 服务器中的用户组如果某个组在 ToolJet 工作区中已存在同名组用户会被自动加入该组头像同步ToolJet 会从 LDAP 服务器查找用户的 profile picture并据此更新 ToolJet 账号的头像。此外首次登录的跳转路径也与老用户不同首次登录用户会被重定向到Workspace Invite工作区邀请页面后续登录用户直接进入 ToolJet Dashboard。这一行为在源码中同样有迹可循oauth/service.ts 中当已存在的用户仍带有invitationToken即账号尚未完成设置时服务端会更新用户来源与状态lifecycleEvents.USER_SSO_VERIFY并返回generateInviteURL生成的邀请链接将用户导向邀请页完成账号激活而已经完成设置的用户则直接通过generateLoginResultPayload生成登录会话进入 Dashboardoauth/service.ts。六、LDAP 登录的用户名规则与登录入口用户在工作区登录页点击 “Sign in withLDAP Name” 按钮后输入的是 LDAP 服务器的用户名与密码。这里需要注意 ToolJet 对用户名的特殊约定用于登录的用户名取自 LDAP 服务器中每个用户对应的common namecn属性。因此登录表单中填写的用户名应与 LDAP 目录中cn属性的值保持一致从 sso_config.entity.ts 中可看到bindAttribute存在cn | upn两种可选绑定属性即说明cn是 ToolJet 登录绑定属性的默认/可选取值之一。配置完成后用户看到的登录页面如下图所示值得强调的是由于 LDAP 登录绑定在 Workspace 级别通过该 URL 登录的用户会被精确地带入所选定的工作区而不是实例首页——多工作区场景下请务必为每个需要 LDAP 登录的工作区分别完成上述配置。七、服务端实现概览进阶对于想深入理解 LDAP 登录链路的开发者可以从服务端源码入手服务接口定义ILdapService.ts 定义了 LDAP 服务的四个核心方法signIn使用用户名/密码 SSO 配置 工作区 slug 完成登录、initializeLdapClient根据配置初始化 LDAP 客户端、unbindLdapClient释放连接与search按 DN 与搜索选项查询目录统一编排入口oauth/service.ts 中OauthService通过依赖注入持有LdapService与SamlService等服务形成统一的 SSO 登录编排层在登录时依据sso类型分发处理并对邮箱域名、用户状态ARCHIVED、邀请令牌等做统一校验配置数据模型sso_config.entity.ts 中的LDAP类型与SSOType.LDAP枚举是配置持久化与前端表单字段对应的最终依据。需要说明的是LDAP 的signIn等具体绑定逻辑在社区版代码中以接口与桩实现throw new Error(Method not implemented)形式存在ldap.service.ts完整实现由对应发行版提供本文以上内容均基于官方 2.50.0-LTS 文档与仓库内可验证的数据结构与流程代码。八、常见问题排查要点结合文档与源码配置与登录过程中遇到问题时可按下述顺序排查连接失败确认Hostname、Port可达防火墙放行对应端口若使用 LDAPS636或 StartTLS需在 SSL 选项中选择 Certificates 并正确上传 Client Key、Client Certificate、Server Certificate 三份材料搜索不到用户检查Base DN是否覆盖了用户所在的目录分支用户名是否使用了cn属性的值新用户无法登录确认 Workspace login 页面中 “Enable Signups” 开关是否开启——关闭状态下只有受邀用户才能通过 SSO 登录对应源码中User does not exist in the workspace异常跳转到邀请页而非 Dashboard这是用户首次登录的正常行为ToolJet 需要先完成账号激活与 Workspace Invite 流程后续登录将直接进入 Dashboard登录进错工作区LDAP 仅支持 Workspace 级别登录请确认使用的 Login URL 来自目标工作区。九、总结通过本文的七个步骤你已经可以在 ToolJet 2.50.0-LTS 中完整落地一套 LDAP 单点登录在 Workspace Settings 中启用 LDAP、填写 Hostname/Port/Base DN 并配置 SSL 证书、生成 Login URL 并分发给用户同时理解首次登录时用户组自动同步、头像同步与邀请页跳转等行为背后的实现机制。LDAP 属于工作区级别的 SSO配置完成后请使用各工作区专属的 Login URL 引导用户登录。【免费下载链接】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），仅供参考
ToolJet LDAP 单点登录（SSO）配置指南：从 Workspace 设置到登录验证全流程
ToolJet LDAP 单点登录SSO配置指南从 Workspace 设置到登录验证全流程【免费下载链接】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/ToolJetLDAPLightweight Directory Access Protocol轻量目录访问协议是许多企业内部最常用的用户目录服务ToolJet 支持将 LDAP 直接作为单点登录SSO来源让用户使用 LDAP 账号免密进入指定工作区。本文以 ToolJet 2.50.0-LTS 文档为骨架完整讲解从 Workspace Settings 开启 LDAP、填写连接参数、配置 SSL 证书、生成登录链接到首次登录行为用户组自动同步、头像同步、邀请页跳转的全部细节并结合仓库源码如 sso_config.entity.ts 与 oauth/service.ts说明底层实现原理。一、前置认知ToolJet 中的 LDAP 支持范围在动手配置前需要先明确 ToolJet 对 LDAP 的两个关键限制这也是官方文档明确指出的LDAP 登录仅在 Workspace工作区级别生效不支持 Instance实例级别。也就是说用户通过 LDAP 登录后只会进入所选的特定工作区而不是整个实例LDAP 配置属于工作区维度的 SSO 配置。从源码看ToolJet 的 SSO 配置统一存放在sso_configs表中sso_config.entity.ts其中configScope字段区分organization与instance两种范围而sso枚举SSOType中明确包含LDAP ldap这一类型sso_config.entity.ts。从 sso_config.entity.ts 可以看到 LDAP 配置在数据结构中的完整形态本文后续所有配置字段都与之对应type LDAP { name: string; host: string; port: number; ssl: boolean; sslOptions: { clientKey: string; clientCert: string; serverCert: string; }; basedn: string; basedns?: string[]; bindAttribute?: cn | upn; enableGroupSync: boolean; };二、开启 LDAP 登录从 Workspace Settings 入口开始配置入口位于 ToolJet 工作区管理界面具体操作如下访问 ToolJet Dashboard点击左侧边栏顶部的 ⚙️齿轮图标打开Workspace Settings。在 Workspace Settings 中找到Workspace login区域选择LDAP标签页。默认情况下LDAP 登录开关处于disabled关闭状态。三、填写 LDAP 连接参数与 SSL 配置点击开关将 LDAP 登录enable启用随后会展开配置表单需要填写以下字段配置项说明Name该 SSO 的名称例如Company LDAP。它会被展示在登录页的 “Sign in withName” 按钮上也会出现在 Login URL 中HostnameLDAP 服务器的主机名或 IP 地址对应源码中的host字段PortLDAP 服务器的端口号对应源码中的port字段。常规 LDAP 使用 389LDAPS 使用 636具体以你的目录服务实际监听端口为准Base DN基础区分名Base Distinguished Name即 LDAP 目录树中搜索用户信息的根节点例如dcexample,dccom对应源码中的basedn字段SSL开启后可以选择 SSL 类型None或Certificates。选择 Certificates 时需额外提供Client Key客户端密钥、Client Certificate客户端证书与Server Certificate服务器证书从源码结构看上述字段最终以 JSON 形式保存在sso_configs.configs列中ssl为布尔开关sslOptions中则对应存放clientKey、clientCert、serverCert三份证书材料sso_config.entity.ts。此外数据结构中还预留了bindAttribute支持cn或upn与enableGroupSync等字段与登录后行为相关详见下文第五、六节。配置完成后点击页面底部的Save Changes按钮保存。四、获取并分发 Login URL保存配置后回到Workspace login页面可以复制到 ToolJet 生成的Login URL。该 URL 可直接用于访问工作区登录页用户在此页面点击 “Sign in withLDAP Name” 按钮并输入 LDAP 用户名与密码即可完成登录。URL 页面上还有一个Enable Signups允许自助注册开关其行为逻辑是开启时通过 SSO 认证后系统会检查用户是否已存在于工作区——如果存在用户可以无缝登录如果不存在则按流程创建/邀请用户允许未被邀请的用户通过 SSO 认证进入关闭时只有已被邀请的用户才能在 SSO 认证成功后登录未受邀用户会收到错误提示。对应到源码工作区登录分支的逻辑位于 oauth/service.ts先按邮箱查询工作区用户状态为 ACTIVE 或 INVITED用户存在则直接走登录/激活流程用户不存在且enableSignUp为真时通过findOrCreateUser创建用户否则抛出User does not exist in the workspace异常。可见 “Enable Signups” 开关直接决定了 SSO 认证后新用户的去留。五、首次登录用户组同步与头像同步首次通过 LDAP 登录时ToolJet 会执行额外的检查与同步操作这是官方文档明确强调的行为用户组自动同步ToolJet 会校验 LDAP 服务器中的用户组如果某个组在 ToolJet 工作区中已存在同名组用户会被自动加入该组头像同步ToolJet 会从 LDAP 服务器查找用户的 profile picture并据此更新 ToolJet 账号的头像。此外首次登录的跳转路径也与老用户不同首次登录用户会被重定向到Workspace Invite工作区邀请页面后续登录用户直接进入 ToolJet Dashboard。这一行为在源码中同样有迹可循oauth/service.ts 中当已存在的用户仍带有invitationToken即账号尚未完成设置时服务端会更新用户来源与状态lifecycleEvents.USER_SSO_VERIFY并返回generateInviteURL生成的邀请链接将用户导向邀请页完成账号激活而已经完成设置的用户则直接通过generateLoginResultPayload生成登录会话进入 Dashboardoauth/service.ts。六、LDAP 登录的用户名规则与登录入口用户在工作区登录页点击 “Sign in withLDAP Name” 按钮后输入的是 LDAP 服务器的用户名与密码。这里需要注意 ToolJet 对用户名的特殊约定用于登录的用户名取自 LDAP 服务器中每个用户对应的common namecn属性。因此登录表单中填写的用户名应与 LDAP 目录中cn属性的值保持一致从 sso_config.entity.ts 中可看到bindAttribute存在cn | upn两种可选绑定属性即说明cn是 ToolJet 登录绑定属性的默认/可选取值之一。配置完成后用户看到的登录页面如下图所示值得强调的是由于 LDAP 登录绑定在 Workspace 级别通过该 URL 登录的用户会被精确地带入所选定的工作区而不是实例首页——多工作区场景下请务必为每个需要 LDAP 登录的工作区分别完成上述配置。七、服务端实现概览进阶对于想深入理解 LDAP 登录链路的开发者可以从服务端源码入手服务接口定义ILdapService.ts 定义了 LDAP 服务的四个核心方法signIn使用用户名/密码 SSO 配置 工作区 slug 完成登录、initializeLdapClient根据配置初始化 LDAP 客户端、unbindLdapClient释放连接与search按 DN 与搜索选项查询目录统一编排入口oauth/service.ts 中OauthService通过依赖注入持有LdapService与SamlService等服务形成统一的 SSO 登录编排层在登录时依据sso类型分发处理并对邮箱域名、用户状态ARCHIVED、邀请令牌等做统一校验配置数据模型sso_config.entity.ts 中的LDAP类型与SSOType.LDAP枚举是配置持久化与前端表单字段对应的最终依据。需要说明的是LDAP 的signIn等具体绑定逻辑在社区版代码中以接口与桩实现throw new Error(Method not implemented)形式存在ldap.service.ts完整实现由对应发行版提供本文以上内容均基于官方 2.50.0-LTS 文档与仓库内可验证的数据结构与流程代码。八、常见问题排查要点结合文档与源码配置与登录过程中遇到问题时可按下述顺序排查连接失败确认Hostname、Port可达防火墙放行对应端口若使用 LDAPS636或 StartTLS需在 SSL 选项中选择 Certificates 并正确上传 Client Key、Client Certificate、Server Certificate 三份材料搜索不到用户检查Base DN是否覆盖了用户所在的目录分支用户名是否使用了cn属性的值新用户无法登录确认 Workspace login 页面中 “Enable Signups” 开关是否开启——关闭状态下只有受邀用户才能通过 SSO 登录对应源码中User does not exist in the workspace异常跳转到邀请页而非 Dashboard这是用户首次登录的正常行为ToolJet 需要先完成账号激活与 Workspace Invite 流程后续登录将直接进入 Dashboard登录进错工作区LDAP 仅支持 Workspace 级别登录请确认使用的 Login URL 来自目标工作区。九、总结通过本文的七个步骤你已经可以在 ToolJet 2.50.0-LTS 中完整落地一套 LDAP 单点登录在 Workspace Settings 中启用 LDAP、填写 Hostname/Port/Base DN 并配置 SSL 证书、生成 Login URL 并分发给用户同时理解首次登录时用户组自动同步、头像同步与邀请页跳转等行为背后的实现机制。LDAP 属于工作区级别的 SSO配置完成后请使用各工作区专属的 Login URL 引导用户登录。【免费下载链接】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），仅供参考
