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 提供方包括OktaActive Directory Federation ServicesADFSAzure ADAuth0其他遵循标准 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与ConfigScopeorganization/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_URLtrueTOOLJET_SERVER_URLURL 必须与 ToolJet 主机地址一致TOOLJET_SERVER_URL必须设置为与 ToolJet 实际对外提供服务的主机地址完全一致否则 SAML 断言校验时实体 ID / 回调地址不匹配会导致认证失败。Google 与 Azure 场景下的环境变量配置当使用Google 或 Azure作为 SAML 提供方时需要额外配置以下环境变量变量值SAML_SET_ENTITY_ID_SERVER_URLtrueTOOLJET_SERVER_URLURL 必须与 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枚举字段标记为samlconfig_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_URLtrueGoogle/Azure 场景用SAML_SET_ENTITY_ID_SERVER_URLtrue两者不叠加TOOLJET_SERVER_URL始终要与 ToolJet 主机地址一致。注册策略影响登录体验未开启 Enable Signups 时新用户必须被邀请后才能通过 SAML 登录开启时已存在用户可无缝登录但新用户仍需预先创建。版本限制多工作区支持从 v2.50.9.46-lts 起生效旧版本请勿依赖该配置。按上述步骤完成配置后你的 ToolJet 工作区即可通过 Okta、ADFS、Azure AD、Auth0 等任意标准 SAML 2.0 提供方实现企业级单点登录统一身份与用户组管理。【免费下载链接】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），仅供参考