ToolJet SAML SSO 配置指南：从身份提供商元数据到工作区登录的完整实践

ToolJet SAML 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 开源仓库中的 SAML Setup 文档 为核心，系统讲解如何在 ToolJet 工作区中启用 SAML（Security Assertion Markup Language）单点登录：包括配置入口、四个关键参数（Provider Name、Identity provider metadata、Group Attribute、Redirect URL）的完整说明、元数据获取方式、用户登录流程，并结合 sso_configs 表实体定义 与 SamlService 接口 等源码，帮助读者理解 SAML 配置在 ToolJet 中的存储模型与认证调用链。读完本文，你将能够独立完成 Okta、Azure AD、ADFS、Auth0 等常见身份提供商与 ToolJet 的 SAML 集成，并能为最终用户提供可直达工作区的 Login URL。

SAML 在 ToolJet 中的定位

Security Assertion Markup Language（SAML）是一种基于 XML 的安全断言协议，它通过在**身份提供商（Identity Provider，IdP）与服务提供商（Service Provider，SP）**之间交换用户身份数据，实现安全的单点登录（SSO）认证。在 ToolJet 中，SAML 属于企业用户管理能力的一部分，与 GitHub、Google、OpenID Connect、LDAP 共同构成 SSO 选项矩阵。

SAML 认证的基本数据流是：用户在 ToolJet 登录页发起登录 → ToolJet 将用户重定向到 IdP → 用户在 IdP 完成身份验证 → IdP 生成包含用户身份与属性的 SAML 断言并回传给 ToolJet → ToolJet 解析断言、校验用户并建立登录会话。整个过程用户无需在 ToolJet 中再输入一次密码，这正是 SSO 的核心价值。

准备工作与前置条件

在开始配置前，请确认：

• 你拥有 ToolJet 工作区的Admin（管理员）角色，只有管理员才能修改工作区登录设置；
• 你已经在某个身份提供商（如 Okta、Azure AD、ADFS、Auth0）中创建了 SAML 2.0 应用，并能获取到该应用的元数据文件（Metadata，通常为 XML）；
• 你的 ToolJet 实例可访问外部 IdP 域名（SAML 采用浏览器重定向，实际约束取决于 IdP 的访问控制）。

说明：ToolJet 支持 SAML 登录于工作区（Workspace）级别，即 SAML 配置与某个具体工作区绑定，用户通过 Login URL 登录时会被明确引导到对应的工作区，而不是全局实例。

在 ToolJet 中启用并配置 SAML

第一步：进入工作区登录设置

1. 登录 ToolJet 后，点击仪表盘左下角的设置图标（⚙️）；
2. 进入Workspace settings（工作区设置）> Workspace login（工作区登录）； 典型 URL 形如https://app.corp.com/nexus/workspace-settings/workspace-login；
3. 在登录设置页面中可以看到各类 SSO 选项。从源码结构看，前端将openid、ldap、saml、google、github列为受保护 SSO 类型（见 WorkspaceLoginSettings.jsx），SAML 会以独立配置项的形式呈现在该页面中。

图：Workspace settings 下的 Workspace login 页面，可在此启用并管理 SAML 等 SSO 选项。

第二步：开启 SAML 开关

SAML 默认处于禁用状态。在「Workspace login」页面中找到 SAML 配置项，将其开关切换为开启（Enabled），即可展开 SAML 配置表单。

图：开启后的 SAML 配置表单，包含 Name、Identity provider metadata、Group Attribute 等字段，底部提供 Cancel 与 Save changes 按钮。

第三步：填写 SAML 配置参数

启用后，需要填写以下四项配置：

填写完成后，点击Save Changes（保存更改）使配置生效。

关于身份提供商元数据的获取

一般地，身份提供商会以XML 文件的形式提供元数据，可从 IdP 的管理后台下载。常见做法有：

• 从 IdP 仪表盘直接下载 metadata 文件，复制 XML 内容粘贴到 ToolJet 的Identity provider metadata字段；
• 许多 IdP（尤其是微软系产品）会暴露一个固定的元数据端点，例如：https://your-identity-provider/federationmetadata/2007-06/federationmetadata.xml

粘贴时请确保 XML 格式完整且未截断，因为元数据中包含 IdP 实体 ID、X.509 签名证书、SSO 绑定端点等关键信息，任何缺失都可能导致后续认证失败。部分 IdP（如 Okta）还允许直接粘贴Metadata URL，由服务端拉取该 URL 对应的 XML，详见下文 Okta 集成章节。

第四步：将 Redirect URL 回填到身份提供商

把 ToolJet 提供的Redirect URL粘贴到 IdP 的 SAML 应用配置中。以 Okta 为例，这一步对应 Okta「Configure SAML」步骤中的Single sign-on URL字段（详见 Okta 集成指南）。在部分 IdP 中还需要配置Audience URI（SP Entity ID），其取值来自元数据 XML 中的entityID属性。

通过 SAML 登录 ToolJet 工作区

配置完成后，最终用户按以下步骤登录：

1. 回到Workspace login标签页，复制页面提供的Login URL。该 URL 形如https://app.corp.com/nexus/workspace-login或带有工作区标识的专属地址；
2. 在浏览器中打开该 Login URL 访问工作区。注意：ToolJet 的 SAML 登录是工作区级别的，用户通过该 URL 登录后会直接进入对应的工作区；
3. 登录页面会醒目地展示你在配置中填写的SAML Provider Name；
4. 点击Sign in withSAML Name按钮，浏览器将被重定向到身份提供商的登录页面；
5. 在 IdP 页面输入企业凭据并点击登录。认证成功后，IdP 将 SAML 断言回传给 ToolJet；
6. ToolJet 通过 SSO 认证流程检查用户是否已存在：
   • 若用户已存在，直接无缝登录进入工作区；
   • 若用户不存在（首次登录且未被预置），则显示错误提示；
   • 若用户是首次登录且账号已创建，会被重定向到 ToolJet 的入门引导（onboarding）页面完成初始化。

图：登录页面上的 SAML 入口，用户可点击「Sign in with SAML」按钮发起 SAML 认证。

深度解析：SAML 配置在 ToolJet 中的存储与认证链路

配置的存储模型：sso_configs 表

从 sso_config.entity.ts 可以确认，所有 SSO 配置统一存储在sso_configs表中，SAML 配置在数据层面表现为：

type SAML = { name: string; // 对应配置表单中的 SAML Provider Name idpMetadata: string; // 对应 Identity provider metadata groupAttribute: string; // 对应 Group Attribute groupSyncEnabled: boolean; // 是否启用组同步 };

该表通过sso枚举字段区分 SSO 类型（google、git、form、openid、ldap、saml），并通过config_scope字段支持**组织级（organization）与实例级（instance）**两种配置范围，organization_id字段则把 SAML 配置与具体工作区绑定——这印证了文档中「SAML 登录是工作区级别」的描述。

认证服务层：SamlService

在服务端，SAML 认证逻辑由 SamlService 承载，其对外接口定义于 ISamlService.ts，包含四个核心方法，恰好对应 SAML 认证链路的四个环节：

其中extraProps携带configId与orgSlug，从侧面印证了 SAML 登录与工作区（组织）绑定的实现方式。在当前的社区版（CE）骨架中，这些方法为待实现占位（抛出Method not implemented），实际能力由对应版本/发行渠道的完整实现提供。

前端入口

前端方面，SAML 配置与登录入口分别位于 WorkspaceLoginSettings.jsx（工作区登录设置页，将saml纳入受保护 SSO 类型列表）与 LoginForm.jsx（登录表单，渲染「Sign in with SAML」入口）。整体调用关系可概括为：前端配置表单 →sso_configs表持久化 → 登录页发起 →SamlService生成授权 URL → IdP 认证 → 断言回传 →signIn完成会话建立。

实战示例：以 Okta 作为身份提供商

Okta 是 SAML 最常见的 IdP 之一，Okta 集成指南 给出了完整的对接步骤，要点如下：

1. 登录 Okta Developer Console，进入Applications，点击Create App Integration，选择SAML 2.0作为 Sign-in method；
2. 在Configure SAML中完成 General 与属性声明配置：
   • Single sign-on URL：填写从 ToolJet SAML 配置页复制的Redirect URL；
   • Audience URI（SP Entity ID）：填写元数据 XML 中的entityID；
   • Name ID format：EmailAddress；Application username：Email；
   • Attribute Statements：声明email（值user.email）与name（值user.firstName）两个属性；
   • Group Attribute Statements：声明groups属性，Filter 选择Matches regex，值设为"*"；
3. 进入应用Sign On标签页，确认Application username format为Email，复制Metadata URL；
4. 回到 ToolJet，将 Okta 的 Metadata URL（或该 URL 对应的 XML 内容）填入Identity provider metadata字段；
5. 保存配置后，使用工作区的Login URL测试 SAML 登录是否成功。

其中 Okta 侧声明的groups属性，正是 ToolJet 配置中Group Attribute字段需要填写的值——两者必须保持一致，组映射才能生效。

常见问题与注意事项

• Group Attribute 不一致：IdP 断言中的组属性名与 ToolJet 配置的 Group Attribute 不一致时，用户无法被正确映射到用户组。请确保两端属性名完全一致。
• 元数据格式错误：粘贴元数据时务必保留完整 XML（含<EntityDescriptor>根节点与签名证书），截断或转义错误会导致 ToolJet 无法与 IdP 建立信任。
• Audience URI 不匹配：IdP 侧配置的 Audience URI（SP Entity ID）必须与 ToolJet 元数据中的entityID对应，否则断言会被拒绝。
• 用户不存在：SAML 登录要求用户已存在于 ToolJet 工作区；未预置的新用户登录会收到错误提示，需由管理员先创建账号。
• 工作区级别限制：SAML 配置属于具体工作区，用户必须通过对应工作区的 Login URL 登录，才能进入该工作区。

小结

本文完整梳理了 ToolJet SAML SSO 的配置流程：从工作区设置入口、启用开关、四项核心参数填写、元数据获取，到最终用户的登录体验，并进一步结合sso_configs实体与SamlService接口解析了 SAML 配置的存储模型与认证调用链，最后以 Okta 为例演示了与真实 IdP 的对接方式。参照本文步骤，配合 SAML Setup 官方文档 与 Okta 集成指南，即可为你的 ToolJet 工作区快速落地 SAML 单点登录。

【免费下载链接】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