docs(sso): role and team mapping with new-member-only defaults

en/platform/configure-sso.mdx

@@ -43,6 +43,8 @@ The egress IPs above apply only to Flashduty's **SaaS (public cloud) service**.
 | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below |
 | Flashduty Service Provider Info | **Service Provider Metadata** and **Assertion Consumer Service URL** (assertion address for identity provider to call for single sign-on) |
 
+You can sync roles and teams by the names returned by your identity provider. See [Role and team mapping](#role-and-team-mapping). **Leave default roles and default teams empty in most cases to keep fallback assignments off.**
+
 ## Configuring OIDC Protocol
 
 ---
@@ -62,6 +64,8 @@ The egress IPs above apply only to Flashduty's **SaaS (public cloud) service**.
 | Scopes | Specifies the information and functionality permissions the request can access, with support for customization. Defaults to `openid`, `profile`, `email`, `phone`; you can add custom scopes as tags |
 | Flashduty Service Provider Info | **Redirect URL**: Identity provider callback address<br />**Supported Signing Algorithms**: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 (HS256 not supported) |
 
+You can sync roles and teams by the names returned by your identity provider. See [Role and team mapping](#role-and-team-mapping). **Leave default roles and default teams empty in most cases to keep fallback assignments off.**
+
 <Warning>
 Scopes is a required field. The default values `openid`, `profile`, `email`, `phone` are the base permissions needed for OIDC to function properly. Removing these defaults may cause single sign-on to fail or prevent correct retrieval of user information. If you need to add custom scopes, add them while keeping the defaults intact.
 </Warning>
@@ -84,6 +88,87 @@ Scopes is a required field. The default values `openid`, `profile`, `email`, `ph
 | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below |
 | Flashduty Service Provider Info | **Redirect URL**: Identity provider callback address |
 
+You can sync roles and teams by the names returned by your identity provider. See [Role and team mapping](#role-and-team-mapping). **Leave default roles and default teams empty in most cases to keep fallback assignments off.**
+
+## Role and team mapping
+
+OIDC, SAML2.0, and CAS support syncing member roles and team membership by the **role names and team names** returned by your identity provider. LDAP continues to use [Group DN mapping](#ldap-role-and-team-synchronization), not the name mapping described here.
+
+**Field mappings apply on every sign-in; defaults apply only when creating members.** After you enable the corresponding sync option and configure the role or team field, valid matches replace the member's existing roles or team memberships on every SSO sign-in, including manually assigned ones. With no matches, existing members keep their assignments; only members actually created during this sign-in receive the configured valid defaults. Roles and teams are handled independently.
+
+<Warning>
+**In most cases, keep default role and default team fallbacks off by leaving both selections empty.**
+
+Defaults apply **only when the current SSO sign-in actually creates a new member and no names match for the corresponding roles or teams**. Existing members do not receive defaults on sign-in, and changing defaults does not reassign their permissions.
+
+Defaults are still shared rules for this SSO configuration, not settings for an individual member. If a mapping field is empty or incorrect, or the identity provider returns no matching names, **every new member created through this SSO configuration without matches receives the same default roles or joins the same default teams**. Do not select defaults just to make a sign-in test work. In particular, do not use administrator or other privileged roles, or sensitive teams, as general defaults.
+</Warning>
+
+### Configuration fields
+
+**Configuration path**: Platform Management → Single Sign-On → Select OIDC, SAML2.0, or CAS → Sync Configuration
+
+| Field | Configuration |
+| --- | --- |
+| Sync roles (`sync_role_enabled`) | When enabled, updates roles from valid mapping results on every SSO sign-in. Without matches, only new members can receive default roles. When disabled, role sync does not run |
+| Role field (`roles`) | The field containing role names, such as `roles`, not a role name or ID. With role sync enabled, matches replace existing roles on **every sign-in**, including manually assigned roles |
+| Default roles (`default_role_ids`) | Supports multiple selections. With role sync enabled and no returned role names matching an available role, **only members created during this sign-in** receive these default roles. Existing members are unaffected. **Usually leave empty** |
+| Sync teams (`sync_team_enabled`) | When enabled, updates team membership from valid mapping results on every SSO sign-in. Without matches, only new members can receive default teams. When disabled, team sync does not run |
+| Team field (`teams`) | The field containing team names, such as `teams`, not a team name or ID. With team sync enabled, matches replace existing team memberships on **every sign-in**, including manually added memberships |
+| Default teams (`default_team_ids`) | Supports multiple selections. With team sync enabled and no returned team names matching an available team, **only members created during this sign-in** receive these default teams. Existing members are unaffected. **Usually leave empty** |
+
+Defaults have no separate toggle: to turn fallback assignments off, clear the default role and default team selections. If you do not want SSO to manage roles or teams, turn off **Sync roles** or **Sync teams**, respectively.
+
+### How names match
+
+- Mapping field names are strings. The returned values can be a single string or an array of strings. Use an array for multiple names: `"A,B"` is treated as one complete name and is not split on commas.
+- Flashduty trims leading and trailing whitespace, matches names exactly and case-sensitively, and removes duplicate names.
+- Roles match the preset names `Admin`, `Responder`, and `Viewer`, or enabled custom roles in the current account. Teams match non-deleted teams in the current account.
+- If multiple eligible roles or teams share a name, Flashduty selects the one with the **smallest ID**. Name mapping does not create roles or teams.
+- OIDC reads the returned claims, SAML reads assertion attributes, and CAS reads returned user attributes. Field names must match what your identity provider actually returns.
+
+For example, if OIDC returns these claims, enter `roles` as the role field and `teams` as the team field:
+
+```json
+{
+  "roles": ["Responder"],
+  "teams": ["Platform", "Database"]
+}
+```
+
+Create the example teams in Flashduty first, and replace the returned values with the names you use. **This mapping example requires no default roles or teams.**
+
+### When defaults apply
+
+Roles and teams **match and fall back independently**. For example, if roles match but teams do not, Flashduty uses the matched roles. A new member can receive default teams; an existing member keeps their current teams.
+
+**A first SSO sign-in does not necessarily create a new member.** Members already created or invited by an administrator, and existing members linked to a stable user ID for the first time, do not receive defaults. Defaults apply only when Just-In-Time (JIT) provisioning creates a new member record during the current sign-in.
+
+| Corresponding sync option | Name matching result | Behavior on sign-in |
+| --- | --- | --- |
+| Off | Any | Does not run this sync; neither mappings nor defaults apply |
+| On | At least one match | Uses the matches without adding defaults; ignores unmatched names |
+| On | No matches, with valid defaults | New members receive the corresponding defaults; existing members keep their assignments |
+| On | No matches and no valid defaults | Does not run this sync: new members follow the existing creation flow; existing members keep their roles or teams |
+
+<Warning>
+**Valid mappings replace assignments; they do not append to them.** On an existing member's next SSO sign-in, valid mapping results can still replace manually assigned roles or teams. A dimension with no matches remains unchanged. To manage roles or teams entirely by hand, disable the corresponding sync option instead of only clearing its defaults.
+</Warning>
+
+### Recommended setup order
+
+<Steps>
+  <Step title="Configure name mapping and leave defaults empty">
+    Confirm that your identity provider returns the correct role and team names for each group of members, then enable the sync options you need. Keep an option off until its mapping is ready.
+  </Step>
+  <Step title="Test members with and without matches">
+    Use test members to check matching names, missing fields, and unmatched names. Sign in again to confirm the actual role and team changes. Test existing members as well as new members.
+  </Step>
+  <Step title="Configure defaults only for an intentional shared fallback">
+    Select default roles or teams only when every new member created through SSO without matches should receive the same minimum required permissions or join the same teams. **Otherwise, leave defaults empty to keep fallback assignments off.** Changing defaults does not affect existing members.
+  </Step>
+</Steps>
+
 ## Configuring LDAP Protocol
 
 ---

zh/platform/configure-sso.mdx

@@ -44,6 +44,8 @@ Flashduty 支持 SAML2.0、OIDC、CAS 和 LDAP（仅私有化版本）协议的
 | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) |
 | Flashduty 服务提供商信息 | **Service Provider Metadata** 和 **Assertion Consumer Service URL**（断言地址，用于身份提供商调用进行单点登录） |
 
+角色和团队可按身份提供商返回的名称同步，详见 [角色和团队映射](#角色和团队映射)。**默认角色和默认团队通常应留空，不启用默认兜底。**
+
 ## 配置 OIDC 协议
 
 ---
@@ -63,6 +65,8 @@ Flashduty 支持 SAML2.0、OIDC、CAS 和 LDAP（仅私有化版本）协议的
 | Scopes | 指定请求可访问的信息和功能权限，支持自定义。默认值为 `openid`、`profile`、`email`、`phone`，支持以标签形式添加自定义 Scope |
 | Flashduty 服务提供商信息 | **Redirect URL**：身份提供商回调地址<br />**支持签名算法**：RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512（不支持 HS256） |
 
+角色和团队可按身份提供商返回的名称同步，详见 [角色和团队映射](#角色和团队映射)。**默认角色和默认团队通常应留空，不启用默认兜底。**
+
 <Warning>
 Scopes 为必填字段。默认值 `openid`、`profile`、`email`、`phone` 是 OIDC 协议正常工作所需的基础权限。删除这些默认值可能导致单点登录失败或无法正确获取用户信息。如需添加自定义 Scope，建议在保留默认值的基础上追加。
 </Warning>
@@ -85,6 +89,87 @@ Scopes 为必填字段。默认值 `openid`、`profile`、`email`、`phone` 是
 | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) |
 | Flashduty 服务提供商信息 | **Redirect URL**：身份提供商回调地址 |
 
+角色和团队可按身份提供商返回的名称同步，详见 [角色和团队映射](#角色和团队映射)。**默认角色和默认团队通常应留空，不启用默认兜底。**
+
+## 角色和团队映射
+
+OIDC、SAML2.0 和 CAS 支持按身份提供商返回的**角色名称、团队名称**同步成员权限和团队归属。LDAP 仍使用 [Group DN 映射](#ldap-角色和团队同步)，不使用本节的名称映射。
+
+**字段映射每次登录生效，默认值仅用于新建成员。** 开启对应同步并配置角色字段或团队字段后，每次 SSO 登录都会用有效匹配结果覆盖成员现有的角色或团队，包括手工分配的数据。没有匹配结果时，已有成员的对应数据保持不变；只有本次登录实际新建的成员才会使用已配置的有效默认值。角色与团队分别处理。
+
+<Warning>
+**绝大多数情况下，请不要启用默认角色和默认团队兜底，保持两项默认值为空。**
+
+默认值**仅在本次 SSO 登录实际创建新成员、且对应角色或团队没有匹配结果时生效**。已有成员登录不会应用默认值，也不会因修改默认值而被重新分配权限。
+
+默认值仍是这份 SSO 配置的统一规则，不是针对某个成员的单独设置。如果映射字段未填写、填写错误，或身份提供商未返回可匹配的名称，**所有通过该 SSO 新建且未匹配的成员都会获得相同的默认角色或加入相同的默认团队**。不要为了让登录测试通过而随意选择默认值，尤其不要将管理员等高权限角色或敏感团队设为通用默认值。
+</Warning>
+
+### 配置字段
+
+**配置路径**：平台管理 → 单点登录 → 选择 OIDC、SAML2.0 或 CAS → 同步配置
+
+| 字段 | 配置方式 |
+| --- | --- |
+| 同步角色（`sync_role_enabled`） | 开启后，每次 SSO 登录按有效映射结果更新角色；无匹配时，仅新建成员可使用默认角色。关闭则不执行角色同步 |
+| 角色字段（`roles`） | 填写返回角色名称的字段名，例如 `roles`，不是角色名称或 ID。开启角色同步后，**每次登录**按匹配结果覆盖现有角色，包括手工分配的角色 |
+| 默认角色（`default_role_ids`） | 可多选。开启角色同步后，若返回的角色名称未匹配到任何可用角色，**仅本次登录新建的成员**会同步这些默认角色；已有成员不受影响。**通常保持为空** |
+| 同步团队（`sync_team_enabled`） | 开启后，每次 SSO 登录按有效映射结果更新团队归属；无匹配时，仅新建成员可使用默认团队。关闭则不执行团队同步 |
+| 团队字段（`teams`） | 填写返回团队名称的字段名，例如 `teams`，不是团队名称或 ID。开启团队同步后，**每次登录**按匹配结果覆盖现有团队，包括手工加入的团队 |
+| 默认团队（`default_team_ids`） | 可多选。开启团队同步后，若返回的团队名称未匹配到任何可用团队，**仅本次登录新建的成员**会同步这些默认团队；已有成员不受影响。**通常保持为空** |
+
+默认值没有独立开关：“不启用默认兜底”是指清空默认角色和默认团队的选择。若您不需要 SSO 管理角色或团队，应关闭对应的**同步角色**或**同步团队**开关。
+
+### 名称如何匹配
+
+- 映射字段名是字符串；身份提供商返回的字段值支持单个字符串或字符串数组。多个名称请使用数组，`"A,B"` 会被视为一个完整名称，不会按逗号拆分。
+- Flashduty 去除名称首尾空格后按名称精确匹配，区分大小写；重复名称会去重。
+- 角色支持预设名称 `Admin`、`Responder`、`Viewer`，以及当前账户中已启用的自定义角色名称；团队匹配当前账户中未删除的团队。
+- 如果多个有效角色或团队同名，选择 **ID 最小**的一项。名称映射不会自动创建角色或团队。
+- OIDC 从返回的 Claims 中取值；SAML 从断言属性中取值；CAS 从返回的用户属性中取值。字段名必须与身份提供商的实际返回保持一致。
+
+例如，OIDC 返回以下 Claims 时，角色字段填写 `roles`，团队字段填写 `teams`：
+
+```json
+{
+  "roles": ["Responder"],
+  "teams": ["Platform", "Database"]
+}
+```
+
+请先在 Flashduty 中创建示例里的团队，并将身份提供商的返回值替换为您实际使用的名称；**无需为这个映射示例配置任何默认值**。
+
+### 默认值何时生效
+
+角色和团队**分别判定、独立回退**。例如，角色匹配成功而团队未匹配时，角色使用映射结果；新建成员可使用默认团队，已有成员则保留原有团队。
+
+**首次 SSO 登录不等于新建成员。** 管理员已创建或邀请的成员，以及首次通过稳定用户 ID 绑定到已有成员的情况，都不使用默认值。只有本次登录通过自动创建成员（JIT）实际新增成员记录时才使用。
+
+| 对应同步开关 | 名称匹配结果 | 登录时的处理 |
+| --- | --- | --- |
+| 关闭 | 任意 | 不执行该项同步，映射字段和默认值均不生效 |
+| 开启 | 至少匹配到一项 | 使用匹配结果，不额外叠加默认值；其他未匹配的名称忽略 |
+| 开启 | 没有匹配结果，有有效默认值 | 新建成员使用该项默认值；已有成员保持原值 |
+| 开启 | 没有匹配结果，也没有有效默认值 | 不执行该项同步：新建成员沿用原有创建流程；已有成员保留原有角色或团队 |
+
+<Warning>
+**有效映射是覆盖更新，不是追加。** 已有成员在下次 SSO 登录时，手工分配的角色或团队仍可能被有效映射结果替换；没有匹配结果的那一项保持不变。若完全由管理员维护角色或团队，请关闭对应同步开关，而不是仅清空默认值。
+</Warning>
+
+### 建议的配置顺序
+
+<Steps>
+  <Step title="先配置名称映射，默认值保持为空">
+    确认身份提供商对各类成员返回正确的角色和团队名称，再开启需要的同步项。未准备好映射的一项先保持同步关闭。
+  </Step>
+  <Step title="分别验证匹配和未匹配的成员">
+    使用测试成员验证正常匹配、字段缺失、名称不匹配三种情况，并重新登录确认角色和团队的实际变化。不要只验证新成员，也要验证已有成员。
+  </Step>
+  <Step title="仅在明确需要统一兜底时配置默认值">
+    只有当您确认所有通过 SSO 新建且未匹配的成员都应获得同一组最低必要权限或加入同一组团队时，才选择默认角色或默认团队。**其他情况保持默认值为空，不启用默认兜底。** 修改默认值不会影响已有成员。
+  </Step>
+</Steps>
+
 ## 配置 LDAP 协议
 
 ---