ToolJet OIDC 组同步（Group Sync）配置与原理详解：从 IdP 自动同步用户角色与自定义组
【免费下载链接】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 的 OIDC 组同步（Group Sync）功能，可以让工作区中的用户角色与自定义组成员关系，随身份提供商（IdP，如 Azure AD、Google、Okta）中的组信息自动更新，实现集中式访问管理。本文以官方文档为主体，结合仓库源码，完整讲解组映射规则、配置步骤、底层数据模型与常见注意事项，帮助管理员在完成 OIDC SSO 接入后，进一步自动化维护用户的角色与组归属。
Group Sync 是什么
在 ToolJet 中，组同步功能用于从身份提供商自动更新用户在 ToolJet 中的用户角色（User Roles）和自定义组（Custom Groups）。它带来的核心价值包括：
- 集中式访问管理：用户权限的增删改统一在 IdP 侧维护，ToolJet 侧无需逐人手工调整；
- 降低人工出错风险：避免手工编辑组时出现遗漏、拼写错误或权限不一致；
- 增强安全性：用户离开团队或组被回收后，权限在下一次登录同步时自动收敛；
- 简化用户 onboarding 流程：新员工加入 IdP 的某个组后，登录 ToolJet 即可自动获得对应权限。
付费功能（Paid feature）：Group Sync 属于付费能力（原文档中以 Premium 徽标标识）。同时需要注意，Group Sync 仅在 Workspace（工作区）级别可用，不能配置在实例级别。
同步时机与覆盖行为
- 每次登录时都会执行组同步：用户登录时，ToolJet 读取 IdP 返回的组信息并与工作区内的组进行比对更新。
- 变化需要重新登录才生效：用户必须注销后重新登录，组/角色变更才会反映到 ToolJet 中。
- 不建议手动编辑组：在 ToolJet 中手工修改用户的组/角色会被后续登录时的同步结果覆盖。
前置条件：先完成 OIDC SSO 配置
组同步是建立在 OIDC SSO 之上的能力，因此在启用 Group Sync 前，需要先完成 OpenID Connect 单点登录的接入。完整的接入步骤见 OpenID Connect 配置指南，核心流程如下：
- 点击仪表盘左下角的设置图标（⚙️）；
- 工作区级别：进入Workspace Settings > Workspace login（示例 URL：
https://app.corp.com/nexus/workspace-settings/workspace-login）；实例级别：进入Settings > Instance login（示例 URL：https://app.corp.com/instance-settings/instance-login）。该步骤需要的角色：实例级别为Super Admin，工作区级别为Admin； - 在右侧的 SSO 客户端列表中，打开OpenID Connect开关（所有客户端开关默认关闭）；
- 在弹出的配置弹窗中，先开启弹窗左上角的启用开关，不填任何参数直接点击Save changes，系统会生成一个Redirect URL，将该 URL 提供给 IdP 以获取凭据；
- 从 IdP 获取并填写Client Id、Client Secret与Well Known URL，再次点击Save changes保存。
ToolJet 官方文档针对常见 IdP 提供了分步接入指南：Azure AD、Google、Okta。SSO 配置完成后，即可在 OIDC 配置中开启 Group Sync。
Group Mapping：组映射的核心规则
组同步的关键在于"映射"——把 IdP 返回的组名翻译成 ToolJet 工作区内的角色或自定义组。ToolJet 遵循以下三条基本原则：
- 默认 1:1 映射，基于组名且区分大小写（case-sensitive）：IdP 中的组名与 ToolJet 工作区内的组名完全一致时，直接按名字匹配；
- 可配置自定义映射：当 IdP 组名与 ToolJet 组名不一致时，可通过 Group mapping 配置规则进行转换；
- 无匹配组的用户，默认归入 end-users 组：这是兜底策略，保证任何登录用户至少获得一个基础归属，不会因组匹配失败而无法访问。
需要说明的是，这里所说的"组"包含两类：ToolJet 的三个默认用户角色（Admin、Builder、End-user，见 User Roles）以及管理员创建的自定义组（见 Custom Groups）。
组映射场景表
原文档给出的五类典型场景可以直观说明映射逻辑：
| IdP 中的组 | ToolJet 中的组 | 角色映射设置 | 结果 |
|---|---|---|---|
| admin、builder、end-user | 存在（用户角色） | 无 | 用户被赋予对应的用户角色。 |
| engineers | 存在 | 无 | 用户被加入engineers自定义组，并根据权限被赋予end-users或builders用户角色。 |
| engineers | engineers— 不存在 developer— 存在 | engineers → developers | 用户被加入developers自定义组，并根据权限被赋予builder或end-user角色。 |
| admin、developers | 存在 | 无 | 用户被加入developers自定义组，并被赋予admin用户角色。 |
| 无组 | 不适用 | 无 | 用户被加入end-users默认组。 |
从这些场景可以看出两个关键行为：
- 当 IdP 组名与 ToolJet默认用户角色名一致（如
admin、builder、end-user）时，直接决定用户角色； - 当 IdP 组名与自定义组匹配时，用户被加入该自定义组，其用户角色（builder 或 end-user）由该组配置的权限推导得出。用户加入具有更高权限的自定义组时，其用户角色会被自动提升，这与 Custom Groups 中描述的"继承与覆盖（Inheritance and Overrides）"机制一致。
在 ToolJet 中配置 OIDC 组同步
配置入口位于工作区设置，操作步骤如下：
- 进入Workspace Settings > Workspace Login标签页；
- 在 SSO 区域点击OpenID Connect；
- 按前文 OIDC 配置指南 完成 SSO 基础配置；
- 开启Group Sync开关，并填写以下两项信息：
- Claim name（声明名称）：填写 OIDC Token 中包含组信息的 claim 名，例如
groups。该值必须与 IdP 在 ID Token 或 UserInfo 端点中返回的声明名一致，否则无法读取到组列表； - Group mapping（组映射）：配置 IdP 组到 ToolJet 组的映射规则，使用以下格式，多个映射用英文逗号分隔：
IdP Group -> ToolJet Group, Another IdP Group -> Another ToolJet Group例如：
Marketing Team -> marketing, Sales Team -> sales上图即 OIDC Group Sync 配置界面（docs/static/img/user-management/group-sync/oidc/mapping.png），可以看到：Group Sync 开关显示绿色 Enabled；Claim name 示例值为groups；Group mapping 示例为Marketing Team -> marketing, Sales Team -> sales, Leadership -> admins；输入框下方有辅助提示"Separate mappings with commas"（用逗号分隔多条映射）；底部提供Cancel与Save changes按钮。
源码视角：组同步的底层实现
组同步配置在服务端有完整的数据模型与持久化逻辑，可以从源码确认其实现细节。
数据模型：sso_config_oidc_group_sync
配置被持久化在独立的sso_config_oidc_group_sync表中，对应实体 sso_config_oidc_group_sync.entity.ts：
claim_name：varchar 类型，存储 Claim name（组信息声明名）；group_mapping：jsonb 类型，存储Record<string, string>形式的组映射键值对（IdP 组名 → ToolJet 组名）；enable_group_sync：boolean 类型，组同步总开关；organization_id：uuid 类型（可空），记录该配置归属的工作区；sso_config_id：关联sso_configs表的外键（onDelete: 'CASCADE'），即组同步配置挂在具体的 OIDC SSO 配置之下，删除 SSO 配置时组同步配置随之级联删除。
同时，sso_config.entity.ts 中也保存了claimName、groupMapping、enableGroupSync字段，说明这两类实体共同支撑 OIDC 场景下的组同步能力。
保存与更新逻辑
在 service.ts 的updateOrganizationSSOConfigs中：
- OIDC 属于多租户（multi-tenant）类型：一个工作区可持有多个 OIDC 配置，通过
configId区分新增或更新（service.ts）； - 当请求体携带
oidcGroupSyncs时，调用oidcGroupSyncRepository.createOrUpdateGroupSync(oidcGroupSyncs, ssoConfig.id)保存组同步配置（service.ts）。
仓库 oidc-group-sync.repository.ts 实现了 upsert 语义：对已存在的记录做合并更新，同时删除该ssoConfigId下不在当前提交列表中的organizationId条目，从而保证组同步配置与界面提交状态一致。从源码结构可以推断，组同步配置支持按工作区（organizationId）维度隔离，这与文档所述"Group Sync 仅工作区级别可用"相互印证。
注意事项与最佳实践
以下注意事项来自官方文档，配置与日常维护时需格外留意：
- 从 IdP 删除用户 ≠ 从 ToolJet 删除用户：当用户从身份提供商中被删除时，管理员需要在 ToolJet 中手动归档（archive）该用户。否则，如果密码登录（password login）仍处于启用状态，该用户依然可以使用密码登录 ToolJet。
- 许可证变化的影响：如果许可证过期，或降级到不含组同步的套餐，SSO 与组同步功能会同时被禁用。此时用户只能通过其他可用的 SSO 方式或邮箱/密码登录。
- 许可证用户数上限：如果许可证的用户数上限已达，新用户将不被允许登录。
- 配合角色体系使用：组同步的结果会落到 User Roles（Admin / Builder / End-user）与自定义组上。建议在工作区中提前规划好组命名（区分大小写）与权限配置，以减少映射规则的维护成本。
总结
ToolJet 的 OIDC 组同步通过"登录时自动比对 IdP 组信息 → 按映射规则更新角色与自定义组"的机制，将用户权限管理收敛到身份提供商一侧。配置时只需在Workspace Settings > Workspace Login > OpenID Connect中开启 Group Sync、填写 Claim name 与 Group mapping 即可；底层由sso_config_oidc_group_sync表与SsoConfigOidcGroupSyncRepository提供持久化与 upsert 保障。使用时应牢记三点：每次登录才同步、手工改组会被覆盖、IdP 删除用户后需在 ToolJet 手动归档。
【免费下载链接】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），仅供参考
