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 工作区中启用 SAMLSecurity 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 LanguageSAML是一种基于 XML 的安全断言协议它通过在**身份提供商Identity ProviderIdP与服务提供商Service ProviderSP**之间交换用户身份数据实现安全的单点登录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第一步进入工作区登录设置登录 ToolJet 后点击仪表盘左下角的设置图标⚙️进入Workspace settings工作区设置 Workspace login工作区登录 典型 URL 形如https://app.corp.com/nexus/workspace-settings/workspace-login在登录设置页面中可以看到各类 SSO 选项。从源码结构看前端将openid、ldap、saml、google、github列为受保护 SSO 类型见 WorkspaceLoginSettings.jsxSAML 会以独立配置项的形式呈现在该页面中。图Workspace settings 下的 Workspace login 页面可在此启用并管理 SAML 等 SSO 选项。第二步开启 SAML 开关SAML 默认处于禁用状态。在「Workspace login」页面中找到 SAML 配置项将其开关切换为开启Enabled即可展开 SAML 配置表单。图开启后的 SAML 配置表单包含 Name、Identity provider metadata、Group Attribute 等字段底部提供 Cancel 与 Save changes 按钮。第三步填写 SAML 配置参数启用后需要填写以下四项配置配置项含义与填写说明SAML Provider Name你的 SAML 身份提供商名称例如Okta、Azure AD。该名称会显示在 ToolJet 登录页面上作为「Sign in withSAML Name」按钮的文案。Identity provider metadata从身份提供商处获取的元数据 XML 内容直接粘贴到该字段中。该元数据包含 IdP 的实体 ID、SSO 端点地址、证书等 SAML 配置细节ToolJet 据此完成与 IdP 的信任关系建立。Group Attribute身份提供商断言中携带用户组信息的属性的名称如groups。ToolJet 会依据该属性将用户映射到工作区中相应的用户组从而实现基于 SAML 断言的分组授权。Redirect URLToolJet 生成的回调地址需复制并粘贴到身份提供商的 SAML 应用配置页中不同 IdP 中可能被称为 Single sign-on URL / ACS URL / Reply URL。该地址告诉 IdP 在用户认证成功后应将 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 URISP Entity ID其取值来自元数据 XML 中的entityID属性。通过 SAML 登录 ToolJet 工作区配置完成后最终用户按以下步骤登录回到Workspace login标签页复制页面提供的Login URL。该 URL 形如https://app.corp.com/nexus/workspace-login或带有工作区标识的专属地址在浏览器中打开该 Login URL 访问工作区。注意ToolJet 的 SAML 登录是工作区级别的用户通过该 URL 登录后会直接进入对应的工作区登录页面会醒目地展示你在配置中填写的SAML Provider Name点击Sign in withSAML Name按钮浏览器将被重定向到身份提供商的登录页面在 IdP 页面输入企业凭据并点击登录。认证成功后IdP 将 SAML 断言回传给 ToolJetToolJet 通过 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 认证链路的四个环节方法职责getSAMLAuthorizationURL(configId, host?)根据配置 ID 生成向 IdP 发起 SAML 认证的授权跳转 URL对应登录流程中「重定向到 IdP」环节saveSAMLResponse(configId, response)保存 IdP 回传的 SAML Response返回其标识供后续流程引用getSAMLAssert(SAMLResponse)解析 SAML Response提取其中的 SAML 断言AssertionsignIn(samlResponseId, configs, extraProps)依据解析出的断言完成用户查找、创建与登录返回用户响应其中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 集成指南 给出了完整的对接步骤要点如下登录 Okta Developer Console进入Applications点击Create App Integration选择SAML 2.0作为 Sign-in method在Configure SAML中完成 General 与属性声明配置Single sign-on URL填写从 ToolJet SAML 配置页复制的Redirect URLAudience URISP Entity ID填写元数据 XML 中的entityIDName ID formatEmailAddressApplication usernameEmailAttribute Statements声明email值user.email与name值user.firstName两个属性Group Attribute Statements声明groups属性Filter 选择Matches regex值设为*进入应用Sign On标签页确认Application username format为Email复制Metadata URL回到 ToolJet将 Okta 的 Metadata URL或该 URL 对应的 XML 内容填入Identity provider metadata字段保存配置后使用工作区的Login URL测试 SAML 登录是否成功。其中 Okta 侧声明的groups属性正是 ToolJet 配置中Group Attribute字段需要填写的值——两者必须保持一致组映射才能生效。常见问题与注意事项Group Attribute 不一致IdP 断言中的组属性名与 ToolJet 配置的 Group Attribute 不一致时用户无法被正确映射到用户组。请确保两端属性名完全一致。元数据格式错误粘贴元数据时务必保留完整 XML含EntityDescriptor根节点与签名证书截断或转义错误会导致 ToolJet 无法与 IdP 建立信任。Audience URI 不匹配IdP 侧配置的 Audience URISP 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
`)
