> ## Documentation Index > Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 单点登录 > 通过单点登录实现一次登录，访问多个关联应用，提高工作效率并增强安全性 Flashduty 支持 SAML2.0、OIDC、CAS 和 LDAP（仅私有化版本）协议的单点登录（SSO）接入，帮助您轻松集成到各种应用和平台中。用户只需登录一次，便可访问多个关联的应用程序和服务，无需重复身份验证。 ## 网络访问要求 *** 不同协议对身份提供商（IdP）的网络可达性要求不同，配置前建议先确认，避免因网络不通导致登录失败： | 协议 | 是否需要 Flashduty 访问身份提供商 | 说明 | | -------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- | | SAML 2.0 | 不需要 | 登录全程通过成员的浏览器完成：浏览器被重定向到身份提供商，登录后再把签名的 SAMLResponse 回传给 Flashduty。Flashduty 服务端不会主动连接身份提供商，签名基于您上传的元数据在本地校验 | | OIDC | 需要 | 每次登录，Flashduty 服务端都需要访问身份提供商的 Discovery 文档、Token 端点和 JWKS 端点；当 ID Token 未携带完整的映射字段时，还会额外访问 UserInfo 端点 | | CAS | 需要 | 每次登录，Flashduty 服务端都需要调用身份提供商的 `/serviceValidate` 接口校验登录票据。CAS 协议本身不提供其他校验方式——票据不携带签名信息，只能回源验证 | | LDAP | 不涉及公网访问 | 仅私有化版本支持，Flashduty 部署在您自有网络内，不存在公网可达性问题 | 如果您的身份提供商部署在内网、无法从公网访问： * 可以将 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 协议类型 | 字段 | 描述 | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | 协议类型 | 选择 SAML2.0 | | 元数据文档 | 通过身份提供商获取的 XML 文档 | | 字段映射 | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名和手机信息 | | 稳定用户 ID 字段（`user_id`） | 可选。身份提供商返回的用户唯一标识属性，用于识别同一成员，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `employee_id`；填写 `name_id` 时取 SAML 断言中的 NameID（Subject）。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | | Flashduty 服务提供商信息 | **Service Provider Metadata** 和 **Assertion Consumer Service URL**（断言地址，用于身份提供商调用进行单点登录） | 角色和团队可按身份提供商返回的名称同步，详见 [角色和团队映射](#角色和团队映射)。**默认角色和默认团队通常应留空，不启用默认兜底。** ## 配置 OIDC 协议 *** **配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 OIDC 协议类型 | 字段 | 描述 | | ------------------------- | ------------------------------------------------------------------------------------------------------------------- | | 协议类型 | 选择 OIDC 协议 | | Issuer | 从身份提供商获取，大小写敏感的 URL，不能包含 query 参数 | | Client ID | 客户端 ID，从身份提供商获取 | | Client Secret | 客户端密钥，从身份提供商获取 | | 字段映射 | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名和手机信息 | | 稳定用户 ID 字段（`user_id`） | 可选。用于识别同一成员的用户唯一标识 Claim，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `sub`。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | | Scopes | 指定请求可访问的信息和功能权限，支持自定义。默认值为 `openid`、`profile`、`email`、`phone`，支持以标签形式添加自定义 Scope | | Flashduty 服务提供商信息 | **Redirect URL**：身份提供商回调地址
**支持签名算法**：RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512（不支持 HS256） | 角色和团队可按身份提供商返回的名称同步，详见 [角色和团队映射](#角色和团队映射)。**默认角色和默认团队通常应留空，不启用默认兜底。** Scopes 为必填字段。默认值 `openid`、`profile`、`email`、`phone` 是 OIDC 协议正常工作所需的基础权限。删除这些默认值可能导致单点登录失败或无法正确获取用户信息。如需添加自定义 Scope，建议在保留默认值的基础上追加。 ## 配置 CAS 协议 *** **配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 CAS 协议类型 | 字段 | 描述 | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | 协议类型 | 选择 CAS 协议 | | CAS 地址 | 从身份提供商获取的 CAS 服务地址，如 `https://xqlsd3irx2gm-demo.authing.cn/cas-idp/669e050856d5b07b4399b242` | | CAS 登录路径 | CAS 登录路径，如 `/login` | | 跳过 TLS 检查 | 可选项，启用后将跳过 TLS 证书验证，适用于使用自签名证书的 CAS 服务 | | 字段映射 | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名和手机信息 | | 稳定用户 ID 字段（`user_id`） | 可选。用于识别同一成员的用户唯一标识，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `principal`（即 CAS 认证用户名），也可配置为 CAS 返回的某个属性。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | | Flashduty 服务提供商信息 | **Redirect URL**：身份提供商回调地址 | 角色和团队可按身份提供商返回的名称同步，详见 [角色和团队映射](#角色和团队映射)。**默认角色和默认团队通常应留空，不启用默认兜底。** ## 角色和团队映射 OIDC、SAML2.0 和 CAS 支持按身份提供商返回的**角色名称、团队名称**同步成员权限和团队归属。LDAP 仍使用 [Group DN 映射](#ldap-角色和团队同步)，不使用本节的名称映射。 **字段映射每次登录生效，默认值仅用于新建成员。** 开启对应同步并配置角色字段或团队字段后，每次 SSO 登录都会用有效匹配结果覆盖成员现有的角色或团队，包括手工分配的数据。没有匹配结果时，已有成员的对应数据保持不变；只有本次登录实际新建的成员才会使用已配置的有效默认值。角色与团队分别处理。 **绝大多数情况下，请不要启用默认角色和默认团队兜底，保持两项默认值为空。** 默认值**仅在本次 SSO 登录实际创建新成员、且对应角色或团队没有匹配结果时生效**。已有成员登录不会应用默认值，也不会因修改默认值而被重新分配权限。 默认值仍是这份 SSO 配置的统一规则，不是针对某个成员的单独设置。如果映射字段未填写、填写错误，或身份提供商未返回可匹配的名称，**所有通过该 SSO 新建且未匹配的成员都会获得相同的默认角色或加入相同的默认团队**。不要为了让登录测试通过而随意选择默认值，尤其不要将管理员等高权限角色或敏感团队设为通用默认值。 ### 配置字段 **配置路径**：平台管理 → 单点登录 → 选择 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 theme={null} { "roles": ["Responder"], "teams": ["Platform", "Database"] } ``` 请先在 Flashduty 中创建示例里的团队，并将身份提供商的返回值替换为您实际使用的名称；**无需为这个映射示例配置任何默认值**。 ### 默认值何时生效 角色和团队**分别判定、独立回退**。例如，角色匹配成功而团队未匹配时，角色使用映射结果；新建成员可使用默认团队，已有成员则保留原有团队。 **首次 SSO 登录不等于新建成员。** 管理员已创建或邀请的成员，以及首次通过稳定用户 ID 绑定到已有成员的情况，都不使用默认值。只有本次登录通过自动创建成员（JIT）实际新增成员记录时才使用。 | 对应同步开关 | 名称匹配结果 | 登录时的处理 | | ------ | --------------- | ---------------------------------- | | 关闭 | 任意 | 不执行该项同步，映射字段和默认值均不生效 | | 开启 | 至少匹配到一项 | 使用匹配结果，不额外叠加默认值；其他未匹配的名称忽略 | | 开启 | 没有匹配结果，有有效默认值 | 新建成员使用该项默认值；已有成员保持原值 | | 开启 | 没有匹配结果，也没有有效默认值 | 不执行该项同步：新建成员沿用原有创建流程；已有成员保留原有角色或团队 | **被任一已保存的 SSO 配置选为默认角色或默认团队的角色或团队无法删除。** 删除该角色或团队会返回 `ReferenceExist`（该资源仍被其他实体引用，无法删除）错误，须先在对应 SSO 配置的**默认角色 / 默认团队**选项中取消选择并保存。该限制在 SSO 或对应同步开关关闭时同样生效——默认值已保存在配置中，重新启用后不能出现悬空的 ID；强制删除角色（`is_force`）也不会绕过。 **有效映射是覆盖更新，不是追加。** 已有成员在下次 SSO 登录时，手工分配的角色或团队仍可能被有效映射结果替换；没有匹配结果的那一项保持不变。若完全由管理员维护角色或团队，请关闭对应同步开关，而不是仅清空默认值。 ### 建议的配置顺序 确认身份提供商对各类成员返回正确的角色和团队名称，再开启需要的同步项。未准备好映射的一项先保持同步关闭。 使用测试成员验证正常匹配、字段缺失、名称不匹配三种情况，并重新登录确认角色和团队的实际变化。不要只验证新成员，也要验证已有成员。 只有当您确认所有通过 SSO 新建且未匹配的成员都应获得同一组最低必要权限或加入同一组团队时，才选择默认角色或默认团队。**其他情况保持默认值为空，不启用默认兜底。** 修改默认值不会影响已有成员。 各协议的名称取值来源、匹配规则与字段保留方式详见 [角色与团队同步](/zh/on-call/integration/sso/role-team-sync)。LDAP 使用 Group DN 映射规则，不使用本节的名称映射与新成员默认值规则。 ## 配置 LDAP 协议 *** LDAP 单点登录仅**私有化版本**支持。 **配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 LDAP 协议类型 | 字段 | 描述 | | ------------------------- | -------------------------------------------------------------------------------------------------------------- | | 协议类型 | 选择 LDAP 协议 | | LDAP 链接 | LDAP 服务地址，如：`ldap://10.10.10.10:389` | | BIND DN | 用于连接 LDAP 的用户名，如：`cn=admin,dc=flashduty,dc=com` | | BIND DN 密码 | 用于连接 LDAP 的密码，将加密存储到数据库中 | | 加密机制 | 支持 **TLS** 和 **StartTLS** 两种加密方式（二者互斥，只能启用一种）。启用任一加密方式后，可选择 **跳过 SSL/TLS 证书验证**；如不跳过，可选填写 SSL/TLS 证书路径 | | 用户 DN | 定义从哪个目录开始搜索用户，如：`ou=people,dc=flashduty,dc=com` | | 认证过滤 | 用于检索用户 DN 信息的自定义 filter 表达式，基本形式为：`(&(mail=%s))`。注意：开始和结束的括号是必须的 | | 字段映射 | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名、手机和 Group 信息。邮箱为必填映射字段，Group 字段默认值为 `memberOf`，用于角色和团队同步 | | 稳定用户 ID 字段（`user_id`） | 可选。用于识别同一成员的用户唯一标识属性，邮箱或手机号变更不影响识别；留空时按下方邮箱/手机号字段匹配成员。建议值为 `uid`，也可使用 `entryUUID` 等稳定属性。详见下文 [成员关联方式](#成员关联方式) | | 登录即创建账号 | 默认开启，关闭后需要先邀请成员才可登录 | | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | 字段映射需要和身份提供商的配置保持一致，否则会导致异常。具体配置可参考 [OpenLDAP 集成指引](/zh/on-call/integration/sso/openldap)。 ### LDAP 连接检测 配置 LDAP 连接信息后，你可以在 **协议与连接** 分区的 LDAP 表单下方点击 **连接检测**，验证 Flashduty 能否成功连接到你的 LDAP 服务器。系统会使用当前填写的 LDAP 链接、BIND DN 和密码尝试建立连接，并返回连接成功或失败的结果。 建议在保存配置前先执行连接检测，确保连接参数正确无误，避免因配置错误导致成员无法通过 LDAP 登录。 ### LDAP 角色和团队同步 当你使用 LDAP 协议时，可以根据用户所属的 LDAP Group 自动同步 Flashduty 中的角色和团队。 **配置路径**：LDAP 设置页面 → 同步配置 在同步配置区域，分别开启 **同步角色** 和/或 **同步团队** 开关。 点击 **添加映射规则**，为每条规则配置以下内容： | 字段 | 说明 | | ------------ | ----------------------------------------------------------------------------- | | **Group DN** | LDAP 中 Group 的完整 Distinguished Name，如 `cn=devops,ou=groups,dc=example,dc=com` | | **映射角色** | 当同步角色开启时可选，选择该 Group 对应的 Flashduty 角色 | | **映射团队** | 当同步团队开启时可选，选择该 Group 对应的 Flashduty 团队 | 当同步角色开启时，你可以配置 **默认角色**。当用户的 LDAP Group 未匹配到任何映射规则时，系统将赋予这些默认角色。 * 你可以添加多条映射规则，每条规则对应一个 LDAP Group * 用户登录时，系统会根据其 LDAP Group 成员关系自动匹配并同步对应的角色和团队 * 映射规则中的 Group DN 必须是 LDAP 中 Group 的完整路径 ## 成员关联方式 *** 单点登录时，系统需要将身份提供商返回的用户与账户内成员进行关联，关联方式取决于 SSO 配置是否设置了**稳定用户 ID 字段**，对新建与既有配置均适用： | 配置 | 关联方式 | | ----------------- | -------------------------------------------------------------------------------------- | | 已配置稳定用户 ID 字段 | 按身份提供商返回的稳定用户 ID 识别同一成员，成员邮箱或手机号变更不影响识别。稳定用户 ID 尚未绑定时，系统会先通过邮箱或手机号匹配既有成员，并建立稳定用户 ID 绑定 | | 未配置稳定用户 ID 字段（留空） | 继续按下方映射的邮箱或手机号字段关联成员，行为保持不变 | 请确保身份提供商始终返回稳定且唯一的用户 ID。映射失败（身份提供商未返回该字段）将导致成员无法登录。 修改身份域相关设置（协议类型、身份提供商地址或稳定用户 ID 字段）会被视为身份域变更，系统将轮换 SSO 配置 ID。既有成员会在下次登录时通过邮箱或手机号重新关联，并绑定新的稳定用户 ID。 ## 强制 SSO 登录 *** `force_sso` 选项用于强制账户内所有成员仅能通过 SSO 登录，从而把身份验证完全收敛到身份提供商。 **配置路径**：平台管理 → 单点登录 → 开启 → 设置 → **成员仅支持 SSO 登录** | 项 | 行为 | | --- | -------------------------------------- | | 字段名 | `force_sso` | | 默认值 | **开启**——首次配置 SSO 时，单点登录设置页中的该开关预置为开启状态 | | 开启后 | 该账户的所有成员只能通过 SSO 登录，密码登录和验证码登录均会被服务端拒绝 | | 关闭后 | 允许成员同时使用 SSO 登录、密码登录与验证码登录 | | 例外 | **无**。账户主体（Owner）与超级管理员也受该限制约束，不存在豁免分支 | 当成员在该选项开启后尝试使用密码或验证码登录时，登录接口会返回错误： ```text theme={null} This account requires SSO login. Password/code login is disabled. ``` 通过密码会话切换账户时，若目标账户开启了该选项，同样会被拒绝并提示：`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 配置 Flashduty SSO 单点登录 通过 Keycloak 配置 Flashduty SSO 单点登录 通过 OpenLDAP 配置 Flashduty SSO 单点登录