角色与团队同步

在 平台管理 → 单点登录 的设置页面中，「同步配置」分区决定成员通过 SSO 登录时如何获得 Flashduty 中的角色与团队：

• SAML2.0 / OIDC / CAS：按身份提供商返回的角色名称 / 团队名称进行匹配（claim / 属性名方式）。名称未匹配时，只有本次登录实际新建的成员使用默认角色 / 默认团队兜底，已有成员保持原值。
• LDAP：不使用名称匹配，而是按用户所属 LDAP Group 的 DN 与映射规则匹配，详见 LDAP 角色和团队同步。

同步在成员每次通过 SSO 登录时触发。本文描述 SAML2.0 / OIDC / CAS 协议的同步配置与匹配规则。

​

同步配置字段

「同步配置」分区包含以下字段： 默认值没有独立开关，清空对应默认值即可关闭兜底。若不希望 SSO 管理角色或团队，应关闭对应同步开关；仅清空默认值不会阻止有效映射在每次登录时覆盖现有数据。

​

匹配规则

角色/团队名称的匹配在 Flashduty 服务端完成，规则如下：

​

名称来源与归一化

• claim / 属性值支持单个字符串或字符串数组；数组中的非字符串元素会被忽略。
• 每个名称去除首尾空格；空名称与重复名称会被去除。去重区分大小写——Ops 与 ops 是两个不同的名称。
• 匹配为精确匹配、区分大小写：Ops 不会匹配 ops。

​

角色匹配

• 预设角色 Admin、Responder、Viewer 始终可匹配（不要求启用状态）。
• 自定义角色必须处于启用状态才会被匹配；已禁用角色即使名称相同也不会命中。
• 同一名称命中多个角色时，取 role_id 最小的角色（例如账户中存在多个名为 Ops 的角色时，命中最小 ID 的那个）。
• 未匹配到任何角色的名称会被跳过（服务端记录告警日志），不影响其他名称的匹配结果。

​

团队匹配

• 仅匹配未删除的团队。
• 同样精确匹配、区分大小写；同名团队取 team_id 最小者。
• 未匹配的团队名称同样跳过。

​

默认角色 / 默认团队兜底

• 仅当本次登录实际创建新成员，且该维度没有任何名称匹配时，才应用有效默认值；角色与团队各自独立判断，互不影响。已有成员登录不使用默认值。
• 默认角色：预设角色（Admin / Responder / Viewer）始终可用；自定义默认角色必须存在且处于启用状态，否则跳过并记录告警日志。
• 默认团队：必须存在且未被删除，否则跳过。
• 最终解析出的角色 ID / 团队 ID 会去重并按 ID 升序排列。

​

各协议取值来源

​

协议切换与字段保留

保存 SSO 配置时，控制台会丢弃不属于当前协议的同步字段（避免切换协议后残留无用配置）：

• LDAP：保留 Group 字段、Group DN 映射规则（role_team_mapping）与默认角色；roles、teams、default_team_ids 不会被保存。
• SAML2.0 / OIDC / CAS：保留 roles、teams、default_role_ids、default_team_ids；group 与映射规则不会被保存。

​

生效时机与覆盖语义

• 同步开启且名称匹配成功时，成员每次通过 SSO 登录都会使用有效映射更新对应角色或团队。
• 有效映射为覆盖式，不是追加：会替换对应的现有数据，包括手工分配的角色或团队，不会与已有数据合并。
• 没有名称匹配时，只有本次登录实际新建的成员使用有效默认值；已有成员的对应角色或团队保持不变。
• 没有名称匹配，也没有有效默认值时，不执行该维度的同步：新建成员沿用原有创建流程，已有成员不会被清空角色或团队。
• 两个同步开关都关闭时，登录不会改动成员的角色与团队。

首次 SSO 登录不等于新建成员。 管理员已经创建或邀请的成员，以及首次通过稳定用户 ID 关联到已有成员的情况，都不会使用默认值；只有本次登录通过自动创建成员（JIT）实际新增成员记录时才使用。修改默认值也不会重新分配已有成员的角色或团队。