Merge pull request #362 from flashcatcloud/feat/sso-role-team-mapping-docs

Feat/sso role team mapping docs

Author: alick-liming

en/on-call/integration/sso/role-team-sync.mdx

@@ -1,16 +1,22 @@
 ---
 title: "Role and Team Sync"
-description: "For SAML2.0, OIDC, and CAS, member roles and teams are synced by exactly matching the role/team names returned by the identity provider (claim/attribute names); default roles/teams apply when no name matches"
+description: "SAML2.0, OIDC, and CAS sync roles and teams by name on every sign-in; without matches, defaults apply only to newly created members and existing members keep their assignments"
 keywords: ["SSO", "single sign-on", "role sync", "team sync", "sync configuration", "claim"]
 ---
 
 In the **Platform Management → Single Sign-On** settings page, the **Sync Configuration** section decides how members get their Flashduty roles and teams when they sign in via SSO:
 
-- **SAML2.0 / OIDC / CAS**: matching by the **role names / team names** returned by the identity provider (claim / attribute names); when no name matches, the configured **default roles / default teams** apply.
+- **SAML2.0 / OIDC / CAS**: matching by the **role names / team names** returned by the identity provider (claim / attribute names). When no name matches, **default roles / default teams** apply only to members actually created during this sign-in; existing members keep their assignments.
 - **LDAP**: does not use name matching; instead it matches the user's **LDAP Group** DN against mapping rules. See [LDAP Role and Team Synchronization](/en/platform/configure-sso#ldap-role-and-team-synchronization).
 
 Sync runs on **every SSO sign-in**. This page describes the sync configuration and matching rules for SAML2.0 / OIDC / CAS.
 
+<Warning>
+**In most cases, leave default roles and default teams empty to keep fallback assignments off.**
+
+Defaults apply only to members actually created during this sign-in without matches for the corresponding names, not to existing members. They are still shared rules for the whole SSO configuration: every new member meeting these conditions receives the same default roles or joins the same default teams. Do not configure general administrator privileges or sensitive teams just to make a sign-in test work.
+</Warning>
+
 ## Sync Configuration Fields
 
 The **Sync Configuration** section contains the following fields:
@@ -21,13 +27,15 @@ The **Sync Configuration** section contains the following fields:
 | Sync Teams (`sync_team_enabled`) | Switch. When on, teams are synced by name; when off, sign-in never changes a member's teams |
 | Role Field (`roles`) | The name of the claim / attribute that carries the **role names** returned by the identity provider, e.g. `roles`. Accepts a string or an array of strings; names are matched exactly |
 | Team Field (`teams`) | The name of the claim / attribute that carries the **team names** returned by the identity provider, e.g. `teams`. Accepts a string or an array of strings; names are matched exactly |
-| Default Roles (`default_role_ids`) | Multi-select of roles (the dropdown lists enabled roles only). Applied when none of the returned role names matches an eligible role |
-| Default Teams (`default_team_ids`) | Multi-select of teams. Applied when none of the returned team names matches a team |
+| Default Roles (`default_role_ids`) | Multi-select of roles (the dropdown lists enabled roles only). With role sync enabled and no names matching an eligible role, defaults apply **only to members created during this sign-in**. Existing members are unaffected. **Usually leave empty** |
+| Default Teams (`default_team_ids`) | Multi-select of teams. With team sync enabled and no names matching an eligible team, defaults apply **only to members created during this sign-in**. Existing members are unaffected. **Usually leave empty** |
 
 <Note>
-If the **Role Field / Team Field is left empty**, no name ever matches: when the corresponding sync switch is on, that dimension falls straight into the default roles / default teams branch at sign-in. With no eligible defaults configured, the result is empty (see [When Sync Takes Effect and Overwrite Semantics](#when-sync-takes-effect-and-overwrite-semantics)).
+If the **Role Field / Team Field is left empty**, no name matches. With the corresponding sync switch on, only newly created members can receive eligible defaults for that dimension; existing members keep their assignments. Without eligible defaults, that dimension is not synced and existing roles or teams are not cleared (see [When Sync Takes Effect and Overwrite Semantics](#when-sync-takes-effect-and-overwrite-semantics)).
 </Note>
 
+Defaults have no separate toggle: clear the corresponding selection to turn fallback assignments off. To stop SSO from managing roles or teams, disable the corresponding sync option; clearing defaults alone does not prevent valid mappings from replacing existing assignments on every sign-in.
+
 ## Matching Rules
 
 Role/team name matching happens on the Flashduty server, with these rules:
@@ -53,7 +61,7 @@ Role/team name matching happens on the Flashduty server, with these rules:
 
 ### Default roles / default teams fallback
 
-- Defaults apply only when the dimension's resolution result is **empty** (no name matched at all); roles and teams fall back **independently** of each other.
+- Eligible defaults apply only when this sign-in **actually creates a new member** and no name matches for that dimension. Roles and teams fall back **independently** of each other. Existing members do not receive defaults on sign-in.
 - Default roles: the preset roles (`Admin` / `Responder` / `Viewer`) are always eligible; a custom default role must **exist and be enabled**, otherwise it is skipped with a warning logged.
 - Default teams: must **exist and not be deleted**, otherwise they are skipped.
 - The resolved role IDs / team IDs are deduplicated and sorted in ascending order.
@@ -76,11 +84,14 @@ When saving the SSO configuration, the console discards sync fields that do not
 
 ## When Sync Takes Effect and Overwrite Semantics
 
-- Sync runs on **every SSO sign-in**: the server resolves role IDs and team IDs from the claim names first, then writes them to the member.
-- The write is **overwrite mode**: the resolved result at sign-in becomes the member's final roles/teams; it is not merged with existing roles/teams.
-- If sync is on but the resolution result is empty (no name matched and no eligible default role/team), the member's roles or teams in that dimension are **cleared**.
+- With sync enabled and matching names, valid mappings update the corresponding roles or teams on **every SSO sign-in**.
+- Valid mappings **replace assignments rather than append to them**, including manually assigned roles or team memberships; they are not merged with existing assignments.
+- Without matching names, eligible defaults apply only to members actually created during this sign-in; existing members keep their corresponding roles or teams.
+- Without matching names or eligible defaults, that dimension is not synced: new members follow the existing creation flow, and existing members' roles or teams are not cleared.
 - When both sync switches are off, sign-in never changes a member's roles or 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 this sign-in. Changing defaults does not reassign existing members' roles or teams.
+
 <CardGroup cols={4}>
   <Card title="Single Sign-On Configuration" icon="shield-check" href="/en/platform/configure-sso">
     Overall configuration guide for every protocol

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,8 +88,89 @@ 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>
+
 <Note>
-**Role and team sync**: For SAML2.0 / OIDC / CAS, the **Sync Configuration** section of the settings page syncs roles/teams by the **role/team names** returned by the identity provider (claim / attribute names) — names are matched exactly (case-sensitive), and when no name matches, the configured **default roles / default teams** apply. LDAP instead uses Group DN mapping rules; the two mechanisms differ. See [Role and Team Sync](/en/on-call/integration/sso/role-team-sync) for the matching rules, per-protocol name sources, and when sync takes effect.
+See [Role and Team Sync](/en/on-call/integration/sso/role-team-sync) for per-protocol name sources, matching rules, and field retention. LDAP uses Group DN mapping, not the name mapping or new-member default rules in this section.
 </Note>
 
 ## Configuring LDAP Protocol
@@ -252,7 +337,7 @@ Before modifying, ensure you have checked your email integration configuration a
 
 <CardGroup cols={4}>
   <Card title="Role and Team Sync" icon="users" href="/en/on-call/integration/sso/role-team-sync">
-    SAML2.0/OIDC/CAS sync roles and teams by name, with default config fallback
+    SAML2.0/OIDC/CAS sync by name on every sign-in; defaults apply only to new members without matches
   </Card>
   <Card title="Authing Integration" icon="shield-check" href="/en/on-call/integration/sso/authing">
     Configure Flashduty SSO single sign-on through Authing