> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 角色与团队同步
> SAML2.0、OIDC、CAS 每次登录按名称同步角色与团队；名称未匹配时，仅本次新建成员使用默认角色或默认团队，已有成员保持原值
在 **平台管理 → 单点登录** 的设置页面中，「同步配置」分区决定成员通过 SSO 登录时如何获得 Flashduty 中的角色与团队：
* **SAML2.0 / OIDC / CAS**：按身份提供商返回的**角色名称 / 团队名称**进行匹配（claim / 属性名方式）。名称未匹配时，只有本次登录实际新建的成员使用**默认角色 / 默认团队**兜底，已有成员保持原值。
* **LDAP**：不使用名称匹配，而是按用户所属 **LDAP Group** 的 DN 与映射规则匹配，详见 [LDAP 角色和团队同步](/zh/platform/configure-sso#ldap-角色和团队同步)。
同步在成员**每次通过 SSO 登录**时触发。本文描述 SAML2.0 / OIDC / CAS 协议的同步配置与匹配规则。
**绝大多数情况下，默认角色和默认团队应保持为空，不启用默认兜底。**
默认值只用于本次登录实际创建、且对应名称未匹配的新成员，不会修改已有成员。但它们是整份 SSO 配置的统一规则：所有符合这些条件的新成员都会获得相同的默认角色或加入相同的默认团队。不要为了登录测试配置通用管理员权限或敏感团队。
## 同步配置字段
「同步配置」分区包含以下字段：
| 字段 | 说明 |
| ------------------------- | ---------------------------------------------------------------------------------- |
| 同步角色（`sync_role_enabled`） | 开关。开启后按名称同步角色；关闭时成员登录不会改动角色 |
| 同步团队（`sync_team_enabled`） | 开关。开启后按名称同步团队；关闭时成员登录不会改动团队 |
| 角色字段（`roles`） | 身份提供商返回的**角色名称**所在的 claim / 属性名，如 `roles`。支持字符串或字符串数组；按名称精确匹配 |
| 团队字段（`teams`） | 身份提供商返回的**团队名称**所在的 claim / 属性名，如 `teams`。支持字符串或字符串数组；按名称精确匹配 |
| 默认角色（`default_role_ids`） | 多选角色（下拉仅列出启用状态的角色）。开启角色同步且返回名称未匹配到任何可用角色时，**仅本次登录新建的成员**同步这些默认角色；已有成员不受影响。**通常留空** |
| 默认团队（`default_team_ids`） | 多选团队。开启团队同步且返回名称未匹配到任何可用团队时，**仅本次登录新建的成员**同步这些默认团队；已有成员不受影响。**通常留空** |
**角色字段 / 团队字段留空**时不会匹配任何名称：若对应的同步开关已开启，只有本次新建成员可以使用该维度的有效默认值；已有成员保持原值。没有有效默认值时，不执行该维度的同步，不会清空已有角色或团队（见下方 [生效时机与覆盖语义](#生效时机与覆盖语义)）。
默认值没有独立开关，清空对应默认值即可关闭兜底。若不希望 SSO 管理角色或团队，应关闭对应同步开关；仅清空默认值不会阻止有效映射在每次登录时覆盖现有数据。
## 匹配规则
角色/团队名称的匹配在 Flashduty 服务端完成，规则如下：
### 名称来源与归一化
* claim / 属性值支持**单个字符串或字符串数组**；数组中的非字符串元素会被忽略。
* 每个名称去除首尾空格；空名称与重复名称会被去除。去重**区分大小写**——`Ops` 与 `ops` 是两个不同的名称。
* 匹配为**精确匹配、区分大小写**：`Ops` 不会匹配 `ops`。
### 角色匹配
* 预设角色 `Admin`、`Responder`、`Viewer` **始终**可匹配（不要求启用状态）。
* 自定义角色必须处于**启用**状态才会被匹配；已禁用角色即使名称相同也不会命中。
* 同一名称命中多个角色时，取 **role\_id 最小**的角色（例如账户中存在多个名为 `Ops` 的角色时，命中最小 ID 的那个）。
* 未匹配到任何角色的名称会被**跳过**（服务端记录告警日志），不影响其他名称的匹配结果。
### 团队匹配
* 仅匹配**未删除**的团队。
* 同样精确匹配、区分大小写；同名团队取 **team\_id 最小**者。
* 未匹配的团队名称同样跳过。
### 默认角色 / 默认团队兜底
* 仅当本次登录**实际创建新成员**，且该维度没有任何名称匹配时，才应用有效默认值；角色与团队**各自独立**判断，互不影响。已有成员登录不使用默认值。
* 默认角色：预设角色（`Admin` / `Responder` / `Viewer`）始终可用；自定义默认角色必须**存在且处于启用状态**，否则跳过并记录告警日志。
* 默认团队：必须**存在且未被删除**，否则跳过。
* 最终解析出的角色 ID / 团队 ID 会去重并按 ID 升序排列。
## 各协议取值来源
| 协议 | 角色/团队名称的取值来源 |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| SAML2.0 | SAML 断言（Assertion）中的属性，属性名即「角色字段 / 团队字段」配置的名称，如 `roles` |
| OIDC | ID Token 中的 claim，claim 名即「角色字段 / 团队字段」配置的名称。当同步已开启而 ID Token 未携带该 claim 时，Flashduty 会额外请求 **UserInfo** 端点，并将其返回的属性与 ID Token 的 claim 合并后进行匹配 |
| CAS | CAS `/serviceValidate` 响应中的属性（attributes），属性名即「角色字段 / 团队字段」配置的名称 |
| LDAP | 不使用 claim 名称：按 Group DN 与「映射规则」（`role_team_mapping`）匹配，并支持默认角色兜底，详见 [LDAP 角色和团队同步](/zh/platform/configure-sso#ldap-角色和团队同步) |
## 协议切换与字段保留
保存 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）实际新增成员记录时才使用。修改默认值也不会重新分配已有成员的角色或团队。
各协议接入的整体配置指引
通过 Authing 配置 Flashduty SSO 单点登录
通过 Keycloak 配置 Flashduty SSO 单点登录
通过 OpenLDAP 配置 Flashduty SSO 单点登录