Skip to main content
Flashduty 支持 SAML2.0、OIDC、CAS 和 LDAP（仅私有化版本）协议的单点登录（SSO）接入，帮助您轻松集成到各种应用和平台中。用户只需登录一次，便可访问多个关联的应用程序和服务，无需重复身份验证。

​
网络访问要求

不同协议对身份提供商（IdP）的网络可达性要求不同，配置前建议先确认，避免因网络不通导致登录失败： 如果您的身份提供商部署在内网、无法从公网访问：
  • 可以将 Flashduty 的出口 IP 47.94.95.118、123.56.8.183、47.94.193.81 和 1.13.19.96 加入防火墙白名单，放通 Flashduty 到身份提供商的访问
  • 如果不希望为身份提供商开放任何公网访问，SAML 2.0 是唯一无需 Flashduty 访问身份提供商的协议，推荐优先选择
以上出口 IP 仅适用于 Flashduty SaaS（公有云）服务。如果您使用的是私有化部署版本，Flashduty 运行在您自己的网络中，出口 IP 由您自身的部署环境决定，请向您的基础设施团队确认，不要使用上述地址。

​
配置 SAML 协议

配置路径：平台管理 → 单点登录 → 开启 → 设置 → 选中 SAML2.0 协议类型 角色和团队可按身份提供商返回的名称同步，详见 角色和团队映射。默认角色和默认团队通常应留空，不启用默认兜底。

​
配置 OIDC 协议

配置路径：平台管理 → 单点登录 → 开启 → 设置 → 选中 OIDC 协议类型 角色和团队可按身份提供商返回的名称同步，详见 角色和团队映射。默认角色和默认团队通常应留空，不启用默认兜底。
Scopes 为必填字段。默认值 openid、profile、email、phone 是 OIDC 协议正常工作所需的基础权限。删除这些默认值可能导致单点登录失败或无法正确获取用户信息。如需添加自定义 Scope，建议在保留默认值的基础上追加。

​
配置 CAS 协议

配置路径：平台管理 → 单点登录 → 开启 → 设置 → 选中 CAS 协议类型 角色和团队可按身份提供商返回的名称同步，详见 角色和团队映射。默认角色和默认团队通常应留空，不启用默认兜底。

​
角色和团队映射

OIDC、SAML2.0 和 CAS 支持按身份提供商返回的角色名称、团队名称同步成员权限和团队归属。LDAP 仍使用 Group DN 映射，不使用本节的名称映射。 字段映射每次登录生效，默认值仅用于新建成员。 开启对应同步并配置角色字段或团队字段后，每次 SSO 登录都会用有效匹配结果覆盖成员现有的角色或团队，包括手工分配的数据。没有匹配结果时，已有成员的对应数据保持不变；只有本次登录实际新建的成员才会使用已配置的有效默认值。角色与团队分别处理。
绝大多数情况下，请不要启用默认角色和默认团队兜底，保持两项默认值为空。默认值仅在本次 SSO 登录实际创建新成员、且对应角色或团队没有匹配结果时生效。已有成员登录不会应用默认值，也不会因修改默认值而被重新分配权限。默认值仍是这份 SSO 配置的统一规则，不是针对某个成员的单独设置。如果映射字段未填写、填写错误，或身份提供商未返回可匹配的名称，所有通过该 SSO 新建且未匹配的成员都会获得相同的默认角色或加入相同的默认团队。不要为了让登录测试通过而随意选择默认值，尤其不要将管理员等高权限角色或敏感团队设为通用默认值。

​
配置字段

配置路径：平台管理 → 单点登录 → 选择 OIDC、SAML2.0 或 CAS → 同步配置 默认值没有独立开关：“不启用默认兜底”是指清空默认角色和默认团队的选择。若您不需要 SSO 管理角色或团队，应关闭对应的同步角色或同步团队开关。

​
名称如何匹配

  • 映射字段名是字符串；身份提供商返回的字段值支持单个字符串或字符串数组。多个名称请使用数组，"A,B" 会被视为一个完整名称，不会按逗号拆分。
  • Flashduty 去除名称首尾空格后按名称精确匹配，区分大小写；重复名称会去重。
  • 角色支持预设名称 Admin、Responder、Viewer，以及当前账户中已启用的自定义角色名称；团队匹配当前账户中未删除的团队。
  • 如果多个有效角色或团队同名，选择 ID 最小的一项。名称映射不会自动创建角色或团队。
  • OIDC 从返回的 Claims 中取值；SAML 从断言属性中取值；CAS 从返回的用户属性中取值。字段名必须与身份提供商的实际返回保持一致。
例如，OIDC 返回以下 Claims 时，角色字段填写 roles，团队字段填写 teams：
请先在 Flashduty 中创建示例里的团队，并将身份提供商的返回值替换为您实际使用的名称；无需为这个映射示例配置任何默认值。

​
默认值何时生效

角色和团队分别判定、独立回退。例如，角色匹配成功而团队未匹配时，角色使用映射结果；新建成员可使用默认团队，已有成员则保留原有团队。 首次 SSO 登录不等于新建成员。 管理员已创建或邀请的成员，以及首次通过稳定用户 ID 绑定到已有成员的情况，都不使用默认值。只有本次登录通过自动创建成员（JIT）实际新增成员记录时才使用。
被任一已保存的 SSO 配置选为默认角色或默认团队的角色或团队无法删除。 删除该角色或团队会返回 ReferenceExist（该资源仍被其他实体引用，无法删除）错误，须先在对应 SSO 配置的默认角色 / 默认团队选项中取消选择并保存。该限制在 SSO 或对应同步开关关闭时同样生效——默认值已保存在配置中，重新启用后不能出现悬空的 ID；强制删除角色（is_force）也不会绕过。
有效映射是覆盖更新，不是追加。 已有成员在下次 SSO 登录时，手工分配的角色或团队仍可能被有效映射结果替换；没有匹配结果的那一项保持不变。若完全由管理员维护角色或团队，请关闭对应同步开关，而不是仅清空默认值。

​
建议的配置顺序

1

先配置名称映射，默认值保持为空

确认身份提供商对各类成员返回正确的角色和团队名称，再开启需要的同步项。未准备好映射的一项先保持同步关闭。
2

分别验证匹配和未匹配的成员

使用测试成员验证正常匹配、字段缺失、名称不匹配三种情况，并重新登录确认角色和团队的实际变化。不要只验证新成员，也要验证已有成员。
3

仅在明确需要统一兜底时配置默认值

只有当您确认所有通过 SSO 新建且未匹配的成员都应获得同一组最低必要权限或加入同一组团队时，才选择默认角色或默认团队。其他情况保持默认值为空，不启用默认兜底。 修改默认值不会影响已有成员。
各协议的名称取值来源、匹配规则与字段保留方式详见 角色与团队同步。LDAP 使用 Group DN 映射规则，不使用本节的名称映射与新成员默认值规则。

​
配置 LDAP 协议

LDAP 单点登录仅私有化版本支持。
配置路径：平台管理 → 单点登录 → 开启 → 设置 → 选中 LDAP 协议类型
字段映射需要和身份提供商的配置保持一致，否则会导致异常。具体配置可参考 OpenLDAP 集成指引。

​
LDAP 连接检测

配置 LDAP 连接信息后，你可以在 协议与连接 分区的 LDAP 表单下方点击 连接检测，验证 Flashduty 能否成功连接到你的 LDAP 服务器。系统会使用当前填写的 LDAP 链接、BIND DN 和密码尝试建立连接，并返回连接成功或失败的结果。
建议在保存配置前先执行连接检测，确保连接参数正确无误，避免因配置错误导致成员无法通过 LDAP 登录。

​
LDAP 角色和团队同步

当你使用 LDAP 协议时，可以根据用户所属的 LDAP Group 自动同步 Flashduty 中的角色和团队。 配置路径：LDAP 设置页面 → 同步配置
1

启用同步

在同步配置区域，分别开启 同步角色 和/或 同步团队 开关。
2

添加映射规则

点击 添加映射规则，为每条规则配置以下内容：
3

配置默认角色

当同步角色开启时，你可以配置 默认角色。当用户的 LDAP Group 未匹配到任何映射规则时，系统将赋予这些默认角色。
  • 你可以添加多条映射规则，每条规则对应一个 LDAP Group
  • 用户登录时，系统会根据其 LDAP Group 成员关系自动匹配并同步对应的角色和团队
  • 映射规则中的 Group DN 必须是 LDAP 中 Group 的完整路径

​
成员关联方式

单点登录时，系统需要将身份提供商返回的用户与账户内成员进行关联，关联方式取决于 SSO 配置是否设置了稳定用户 ID 字段，对新建与既有配置均适用：
请确保身份提供商始终返回稳定且唯一的用户 ID。映射失败（身份提供商未返回该字段）将导致成员无法登录。
修改身份域相关设置（协议类型、身份提供商地址或稳定用户 ID 字段）会被视为身份域变更，系统将轮换 SSO 配置 ID。既有成员会在下次登录时通过邮箱或手机号重新关联，并绑定新的稳定用户 ID。

​
强制 SSO 登录

force_sso 选项用于强制账户内所有成员仅能通过 SSO 登录，从而把身份验证完全收敛到身份提供商。 配置路径：平台管理 → 单点登录 → 开启 → 设置 → 成员仅支持 SSO 登录 当成员在该选项开启后尝试使用密码或验证码登录时，登录接口会返回错误：
通过密码会话切换账户时，若目标账户开启了该选项，同样会被拒绝并提示：The target account requires SSO login. Switching via password session is not allowed.
操作风险：开启 force_sso 后，如果身份提供商（IdP）未正确连通，所有成员都将无法登录该账户，包括账户主体。在打开该开关前，请务必：
  1. 使用任一具备 SSO 登录能力的成员账号端到端验证 SSO 登录链路。
  2. 至少保留一条已可正常通过 SSO 登录的账户主体路径，避免锁出。
  3. 若身份提供商配置可能临时不可用，请先关闭该选项，待修复后再启用。

​
与「禁止编辑外部成员」的区别

force_sso 控制的是登录方式——是否允许密码/验证码登录；sso_user_non_editable（禁止编辑外部成员）控制的是编辑权限——通过 SSO 同步创建的外部成员是否能在控制台中修改资料与角色。两者作用层面不同，可独立开启或关闭。

​
外部成员管理

当您启用单点登录后，通过 SSO 首次登录并自动创建的成员会被标记为外部成员。您可以在 SSO 设置中开启禁止编辑外部成员选项（默认关闭），启用后，这些外部成员在 Flashduty 中将变为只读状态——无法在 Flashduty 中修改其角色或删除该成员，所有成员信息的管理只能通过身份提供商完成。 此功能适用于需要统一在身份提供商中管理用户权限的场景，确保 Flashduty 中的成员信息始终与身份提供商保持一致。
  • 该选项仅影响通过 SSO 创建的外部成员，手动邀请的成员不受影响
  • 如果 SSO 配置被删除，已存在的外部成员将默认保持只读状态

​
登录域名管理

登录域名是识别您的主体账号的重要依据，用于单点登录时定位到正确的 SSO 配置。每个主体的登录域名全局唯一。 配置登录域名后，成员可以通过 {域名}.sso.flashcat.cloud 地址直接发起单点登录，无需手动选择身份提供商。 您可以在 平台管理 → 组织 → 组织信息 → 组织资料 页面修改主体账号的域名。修改域名时请注意，域名只能使用 5–40 位字母、数字或 -，且不能以 - 开头或结尾。
修改域名后，该域名将应用于以下场景：
  • SSO 单点登录配置：所有已配置的 SSO 登录域名会随之变更，成员需要使用新域名发起单点登录
  • 邮件集成推送的邮箱地址：邮件集成的接收地址格式为 prefix@{域名}.{邮箱后缀}，域名变更后地址也会随之变化，请及时更新相关配置
修改前请确认已检查邮件集成配置，并在组织内进行了通报。修改操作可能需要通过多因素认证（MFA）验证。如在使用过程中遇到任何问题，请及时联系技术支持。
  • 建议使用公司英文名称作为登录域名，便于记忆
  • 登录域名一旦设置，变更后原域名将立即失效，使用旧域名的成员需要更新登录地址

​
最佳实践

角色与团队同步

SAML2.0/OIDC/CAS 每次登录按名称同步，未匹配时仅新建成员使用默认配置

Authing 集成

通过 Authing 配置 Flashduty SSO 单点登录

Keycloak 集成

通过 Keycloak 配置 Flashduty SSO 单点登录

OpenLDAP 集成

通过 OpenLDAP 配置 Flashduty SSO 单点登录