ToolJet 工作区 SAML 单点登录配置与登录流程实战指南（v2.50.0-LTS）-编程实验室

ToolJet 工作区 SAML 单点登录配置与登录流程实战指南（v2.50.0-LTS）

【免费下载链接】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 v2.50.0-LTS 版本文档为基础，系统讲解如何在 ToolJet 工作区（Workspace）级别启用 SAML 单点登录（SSO），覆盖 Okta、Active Directory Federation Services (ADFS)、Azure AD、Auth0 等主流身份提供方（IdP）的接入配置、多工作区与 Google/Azure 场景下的环境变量要求，以及用户通过 SAML 完成登录的完整链路。读完本文，你将能够在自托管 ToolJet 实例中独立完成 SAML 的配置、验证与排障，并从源码层面理解 SAML 配置的存储结构与认证路由实现。

SAML 在 ToolJet 中的定位与适用场景

ToolJet 支持基于 SAML 协议的工作区级单点登录。所谓"工作区级"，意味着登录行为与具体的工作区（Workspace）绑定——用户通过某个工作区的登录地址登录后，只会进入该选定的工作区，而不是全局跳转。支持的 SAML 提供方包括：

Okta
Active Directory Federation Services（ADFS）
Azure AD
Auth0
其他遵循标准 SAML 2.0 的 SSO 提供方

从源码看，SAML 是 ToolJet SSO 体系中的一等公民。sso_config.entity.ts 中明确定义了 SAML 配置的数据结构：

type SAML = { name: string; // SAML Provider Name，显示在登录页上的提供方名称 idpMetadata: string; // 身份提供方元数据（XML 内容） groupAttribute: string; // 携带用户组信息的属性名，用于用户组映射 groupSyncEnabled: boolean; // 是否启用组同步 };

该实体还通过枚举SSOType（值为google、git、form、openid、ldap、saml）与ConfigScope（organization/instance）区分不同 SSO 类型与配置作用域，所有 SSO 配置统一持久化在数据库的sso_configs表中，SAML 只是其中一条按sso = 'saml'标记的记录。

配置 SAML：工作区设置操作步骤

启用 SAML 认证只需在 ToolJet 界面完成以下 4 步：

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

打开Workspace Settings（工作区设置）>Workspace login（工作区登录）页面：

该页面由前端模块 WorkspaceLoginSettings.jsx 渲染，其中protectedSSO = ['openid', 'ldap', 'saml', 'google', 'github']表明 SAML 属于受管控的企业级 SSO 选项；而在 BaseSSOConfigurationList.jsx 中，SAML 同样位列受保护配置列表，并配有独立的图标与配置卡片。

第 2 步：开启 SAML 开关

SAML 默认处于禁用状态，需要手动将开关切换为启用：

第 3 步：填写 SAML 配置信息

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

配置项	说明
SAML Provider Name	输入你的 SAML 提供方名称。该名称会显示在登录页面上，作为登录按钮与欢迎文案的一部分
Identity provider metadata	上传身份提供方提供的元数据文件内容。该文件包含 IdP 侧的 SAML 配置细节（实体 ID、证书、断言消费端点等）
Group Attribute	输入包含用户组信息的属性名。该属性用于将用户映射到 ToolJet 中合适的用户组
Redirect URL	复制 ToolJet 生成的 Redirect URL，粘贴到 SAML 提供方的配置页面中（作为 Assertion Consumer Service URL / ACS URL 使用）

关于 Redirect URL 的源码佐证：前端登录/授权流程中，ToolJet 通过 Authorize.jsx 判断 URL 中是否携带saml_response_id参数来判定 SAML 认证是否成功，并将其并入认证参数提交；后端则在 controller.ts 中暴露了三条 SAML 相关路由——GET /oauth/saml/configs/:configId（获取 SAML 授权跳转地址）、POST /oauth/saml/:configId（接收 IdP 回传的 SAML Response）、以及通用的POST /sso/sign-in/common/:ssoType（统一登录入口，ssoType = 'saml'时走 SAML 分支）。Redirect URL 正是让 IdP 能够把断言回传到上述回调路由的桥梁。

第 4 步：保存配置

确认信息无误后，点击Save Changes（保存更改）即可生效。

提示：从身份提供方下载元数据

一般地，身份提供方的元数据以XML 文件形式提供，可从 IdP 的管理后台下载。具体做法：

打开 IdP 的 Dashboard，找到"Metadata / SAML Metadata"相关下载入口；
将 XML 文件中的元数据完整复制，粘贴到 ToolJet 的 SAML SSO 配置的 Identity provider metadata 输入框中；
确保粘贴格式正确，因为该元数据包含 IdP 用于认证的关键配置细节（证书、端点地址等），格式错误将导致认证失败。

此外，很多 IdP 会提供固定地址的元数据端点，例如以下通用格式（将<your-identity-provider>替换为你的 IdP 域名）：

https://<your-identity-provider>/federationmetadata/2007-06/federationmetadata.xml

多工作区场景下的环境变量配置

ToolJet 的**多工作区（multiple workspaces）**功能仅在v2.50.9.46-lts 及之后版本可用。若你正在使用多工作区功能，需要在部署 ToolJet 的服务端配置如下环境变量：

变量	值
`SAML_SET_ENTITY_ID_REDIRECT_URL`	`true`
`TOOLJET_SERVER_URL`	`<URL 必须与 ToolJet 主机地址一致>`

TOOLJET_SERVER_URL必须设置为与 ToolJet 实际对外提供服务的主机地址完全一致，否则 SAML 断言校验时实体 ID / 回调地址不匹配，会导致认证失败。

Google 与 Azure 场景下的环境变量配置

当使用Google 或 Azure作为 SAML 提供方时，需要额外配置以下环境变量：

变量	值
`SAML_SET_ENTITY_ID_SERVER_URL`	`true`
`TOOLJET_SERVER_URL`	`<URL 必须与 ToolJet 主机地址一致>`

注意：如果已经启用了多工作区设置，则无需再配置SAML_SET_ENTITY_ID_SERVER_URL变量——两者只会同时生效其一，避免实体 ID 计算方式冲突。

使用 SAML 登录工作区

完成配置后，用户即可通过 SAML 登录工作区，完整流程如下：

第 1 步：获取登录 URL 并决定注册策略

进入Workspace login页面，复制页面提供的Login URL：

与此同时，你可以自主决定是否开启Enable Signups（允许注册）：

开启时：通过 SSO 认证时，系统会检查用户是否已存在。若已存在，可直接无缝登录；若不存在，则会显示错误（即必须由管理员预先创建/邀请用户，不能自动注册新用户）。
关闭时：只有被邀请的用户才能在 SSO 认证成功后登录。

第 2 步：通过 Login URL 访问工作区

将上一步获得的Login URL分发给用户，用于访问对应工作区。如前所述，ToolJet 的 SAML 登录是工作区级别的，确保用户精确登录到所选工作区。登录页面会醒目地展示你在工作区设置中配置的 SAML 提供方名称：

前端在渲染登录页时会读取工作区的 SSO 配置——LoginForm.jsx 与 AppLoginPage.jsx 均通过configs?.saml?.enabled判断 SAML 是否启用，从而决定是否展示"Sign in with SAML"入口。

第 3 步：点击 SAML 登录按钮

点击Sign in with `SAML Name`按钮（SAML Name即你在配置中填写的 Provider Name），浏览器将被重定向到 SAML 提供方的登录页面：

第 4 步：输入凭据并完成登录

在 IdP 页面输入用户凭据并点击Login。认证成功后：

若用户是首次登录，会被重定向到 ToolJet 的 Onboarding（新用户引导）页面；
若用户已存在，则直接进入工作区。

从源码理解 SAML 的完整认证链路

将界面操作与仓库源码对应起来，可以看到 SAML 在 ToolJet 中的实现脉络：

配置存储：SAML 配置（名称、元数据、组属性、组同步开关）以 JSON 形式存放在sso_configs表的configs列中，sso枚举字段标记为saml，config_scope决定其作用域是组织级还是实例级，enabled字段控制开关状态（见 sso_config.entity.ts）。
服务端接口：认证模块的 controller.ts 统一挂载在oauth/sso路由前缀下，负责接收 SAML 授权请求与 IdP 回传的断言响应；对应的接口定义见 ISamlService.ts，其中getSAMLAuthorizationURL、getSAMLAssert、saveSAMLResponse分别承担构造跳转地址、解析断言、暂存响应等职责。
前端对接：授权页 Authorize.jsx 通过识别 URL 中的saml_response_id完成 SAML 登录状态的确认与回传，形成"登录页 → IdP → 回调 → 会话建立"的闭环。
SSO 开关与能力控制：SAML 属于受许可证保护的企业功能，feature.ts 中为OAUTH_SAML_CONFIGS与OAUTH_SAML_RESPONSE注册了特性键，未授权实例访问相关路由时会被拒绝（这也是为什么自托管社区版默认看不到 SAML 配置入口的原因之一）。

常见注意事项小结

元数据格式必须正确：Identity provider metadata 需完整粘贴 XML 内容，任何截断或格式错误都会导致 SAML 握手失败。
Redirect URL 双向配置：ToolJet 生成的 Redirect URL 必须回填到 IdP 侧的 ACS/回调配置中，两端地址必须严格一致。
环境变量随部署场景而定：多工作区用SAML_SET_ENTITY_ID_REDIRECT_URL=true；Google/Azure 场景用SAML_SET_ENTITY_ID_SERVER_URL=true；两者不叠加；TOOLJET_SERVER_URL始终要与 ToolJet 主机地址一致。
注册策略影响登录体验：未开启 Enable Signups 时，新用户必须被邀请后才能通过 SAML 登录；开启时已存在用户可无缝登录，但新用户仍需预先创建。
版本限制：多工作区支持从 v2.50.9.46-lts 起生效，旧版本请勿依赖该配置。

按上述步骤完成配置后，你的 ToolJet 工作区即可通过 Okta、ADFS、Azure AD、Auth0 等任意标准 SAML 2.0 提供方实现企业级单点登录，统一身份与用户组管理。

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