> ## 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.
# Role and Team Sync
> 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
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, **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.
**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.
## Sync Configuration Fields
The **Sync Configuration** section contains the following fields:
| Field | Description |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sync Roles (`sync_role_enabled`) | Switch. When on, roles are synced by name; when off, sign-in never changes a member's roles |
| 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). 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** |
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)).
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:
### Name normalization
* The claim / attribute value can be a **single string or an array of strings**; non-string elements in an array are ignored.
* Each name is trimmed of leading/trailing whitespace; empty names and duplicates are removed. Deduplication is **case-sensitive** — `Ops` and `ops` are two different names.
* Matching is **exact and case-sensitive**: `Ops` does not match `ops`.
### Role matching
* The preset roles `Admin`, `Responder`, and `Viewer` are **always** eligible (no enabled-state requirement).
* Custom roles must be **enabled** to match; a disabled role with the same name is never hit.
* When one name hits several roles, the role with the **smallest role\_id** wins (e.g. if the account has several roles named `Ops`, the smallest ID is used).
* Names that match no role are **skipped** (the server logs a warning); other names are still resolved.
### Team matching
* Only **non-deleted** teams are matched.
* Also exact and case-sensitive; duplicate team names resolve to the **smallest team\_id**.
* Unmatched team names are skipped as well.
### Default roles / default teams fallback
* 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.
## Where Each Protocol Reads the Names
| Protocol | Source of role/team names |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SAML2.0 | Attributes of the SAML assertion; the attribute name is what you configure in the Role/Team Field, e.g. `roles` |
| OIDC | Claims of the ID Token; the claim name is what you configure in the Role/Team Field. When sync is enabled and the ID Token does not carry that claim, Flashduty additionally calls the **UserInfo** endpoint and merges its attributes with the ID Token claims before matching |
| CAS | Attributes of the CAS `/serviceValidate` response; the attribute name is what you configure in the Role/Team Field |
| LDAP | Does not use claim names: matches Group DN against the mapping rules (`role_team_mapping`), with default-role fallback. See [LDAP Role and Team Synchronization](/en/platform/configure-sso#ldap-role-and-team-synchronization) |
## Protocol Switching and Field Retention
When saving the SSO configuration, the console discards sync fields that do not belong to the current protocol (so switching protocols leaves no stale config behind):
* **LDAP**: keeps the Group field, the Group DN mapping rules (`role_team_mapping`), and the default roles; `roles`, `teams`, and `default_team_ids` are not saved.
* **SAML2.0 / OIDC / CAS**: keeps `roles`, `teams`, `default_role_ids`, and `default_team_ids`; `group` and the mapping rules are not saved.
## When Sync Takes Effect and Overwrite Semantics
* 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.
Overall configuration guide for every protocol
Configuring Flashduty SSO via Authing
Configuring Flashduty SSO via Keycloak
Configuring Flashduty SSO via OpenLDAP