> ## 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.

# 单点登录

> 通过单点登录实现一次登录，访问多个关联应用，提高工作效率并增强安全性

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

## 配置 SAML 协议

***

**配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 SAML2.0 协议类型

| 字段                        | 描述                                                                                       |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| 协议类型                      | 选择 SAML2.0                                                                               |
| 元数据文档                     | 通过身份提供商获取的 XML 文档                                                                        |
| 字段映射                      | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名和手机信息                                                    |
| 登录即创建账号                   | 默认开启，关闭后需要先邀请成员才可登录                                                                      |
| 成员仅支持 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 通过映射字段从身份提供商提取用户邮箱、用户名和手机信息                                                                               |
| 登录即创建账号                   | 默认开启，关闭后需要先邀请成员才可登录                                                                                                 |
| 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录)                                               |
| 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>

## 配置 CAS 协议

***

**配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 CAS 协议类型

| 字段                        | 描述                                                                                           |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| 协议类型                      | 选择 CAS 协议                                                                                    |
| CAS 地址                    | 从身份提供商获取的 CAS 服务地址，如 `https://xqlsd3irx2gm-demo.authing.cn/cas-idp/669e050856d5b07b4399b242` |
| CAS 登录路径                  | CAS 登录路径，如 `/login`                                                                          |
| 跳过 TLS 检查                 | 可选项，启用后将跳过 TLS 证书验证，适用于使用自签名证书的 CAS 服务                                                       |
| 字段映射                      | Flashduty 通过映射字段从身份提供商提取用户邮箱、用户名和手机信息                                                        |
| 登录即创建账号                   | 默认开启，关闭后需要先邀请成员才可登录                                                                          |
| 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录)                        |
| Flashduty 服务提供商信息         | **Redirect URL**：身份提供商回调地址                                                                   |

## 配置 LDAP 协议

***

<Note>
  LDAP 单点登录仅**私有化版本**支持。
</Note>

**配置路径**：平台管理 → 单点登录 → 开启 → 设置 → 选中 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`，用于角色和团队同步              |
| 登录即创建账号                   | 默认开启，关闭后需要先邀请成员才可登录                                                                                    |
| 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录)                                  |

<Tip>
  字段映射需要和身份提供商的配置保持一致，否则会导致异常。具体配置可参考 [OpenLDAP 集成指引](/zh/on-call/integration/sso/openldap)。
</Tip>

### LDAP 连接检测

配置 LDAP 连接信息后，你可以点击设置抽屉底部的 **连接检测** 按钮，验证 Flashduty 能否成功连接到你的 LDAP 服务器。系统会使用当前填写的 LDAP 链接、BIND DN 和密码尝试建立连接，并返回连接成功或失败的结果。

<Tip>
  建议在保存配置前先执行连接检测，确保连接参数正确无误，避免因配置错误导致成员无法通过 LDAP 登录。
</Tip>

### LDAP 角色和团队同步

当你使用 LDAP 协议时，可以根据用户所属的 LDAP Group 自动同步 Flashduty 中的角色和团队。

**配置路径**：LDAP 设置页面 → 同步配置

<Steps>
  <Step title="启用同步">
    在同步配置区域，分别开启 **同步角色** 和/或 **同步团队** 开关。
  </Step>

  <Step title="添加映射规则">
    点击 **添加映射规则**，为每条规则配置以下内容：

    | 字段           | 说明                                                                            |
    | ------------ | ----------------------------------------------------------------------------- |
    | **Group DN** | LDAP 中 Group 的完整 Distinguished Name，如 `cn=devops,ou=groups,dc=example,dc=com` |
    | **映射角色**     | 当同步角色开启时可选，选择该 Group 对应的 Flashduty 角色                                         |
    | **映射团队**     | 当同步团队开启时可选，选择该 Group 对应的 Flashduty 团队                                         |
  </Step>

  <Step title="配置默认角色">
    当同步角色开启时，你可以配置 **默认角色**。当用户的 LDAP Group 未匹配到任何映射规则时，系统将赋予这些默认角色。
  </Step>
</Steps>

<Note>
  * 你可以添加多条映射规则，每条规则对应一个 LDAP Group
  * 用户登录时，系统会根据其 LDAP Group 成员关系自动匹配并同步对应的角色和团队
  * 映射规则中的 Group DN 必须是 LDAP 中 Group 的完整路径
</Note>

## 强制 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.`

<Warning>
  **操作风险**：开启 `force_sso` 后，如果身份提供商（IdP）未正确连通，所有成员都将无法登录该账户，包括账户主体。在打开该开关前，请务必：

  1. 使用任一具备 SSO 登录能力的成员账号端到端验证 SSO 登录链路。
  2. 至少保留一条已可正常通过 SSO 登录的账户主体路径，避免锁出。
  3. 若身份提供商配置可能临时不可用，请先关闭该选项，待修复后再启用。
</Warning>

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

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

## 外部成员管理

***

当您启用单点登录后，通过 SSO 首次登录并自动创建的成员会被标记为**外部成员**。您可以在 SSO 设置中开启**禁止编辑外部成员**选项（默认关闭），启用后，这些外部成员在 Flashduty 中将变为只读状态——无法在 Flashduty 中修改其角色或删除该成员，所有成员信息的管理只能通过身份提供商完成。

此功能适用于需要统一在身份提供商中管理用户权限的场景，确保 Flashduty 中的成员信息始终与身份提供商保持一致。

<Note>
  * 该选项仅影响通过 SSO 创建的外部成员，手动邀请的成员不受影响
  * 如果 SSO 配置被删除，已存在的外部成员将默认保持只读状态
</Note>

## 登录域名管理

***

登录域名是识别您的主体账号的重要依据，用于单点登录时定位到正确的 SSO 配置。每个主体的登录域名全局唯一。

配置登录域名后，成员可以通过 `{域名}.sso.flashcat.cloud` 地址直接发起单点登录，无需手动选择身份提供商。

您可以在 **平台管理 → 基本信息** 页面修改主体账号的域名。修改域名时请注意，域名只能使用 5–40 位字母、数字或 `-`，且不能以 `-` 开头或结尾。

<Warning>
  修改域名后，该域名将应用于以下场景：

  * **SSO 单点登录配置**：所有已配置的 SSO 登录域名会随之变更，成员需要使用新域名发起单点登录
  * **邮件集成推送的邮箱地址**：邮件集成的接收地址格式为 `prefix@{域名}.{邮箱后缀}`，域名变更后地址也会随之变化，请及时更新相关配置

  修改前请确认已检查邮件集成配置，并在组织内进行了通报。修改操作可能需要通过多因素认证（MFA）验证。如在使用过程中遇到任何问题，请及时联系技术支持。
</Warning>

<Note>
  * 建议使用公司英文名称作为登录域名，便于记忆
  * 登录域名一旦设置，变更后原域名将立即失效，使用旧域名的成员需要更新登录地址
</Note>

## 最佳实践

***

<CardGroup cols={3}>
  <Card title="Authing 集成" icon="shield-check" href="/zh/on-call/integration/sso/authing">
    通过 Authing 配置 Flashduty SSO 单点登录
  </Card>

  <Card title="Keycloak 集成" icon="key" href="/zh/on-call/integration/sso/keycloak">
    通过 Keycloak 配置 Flashduty SSO 单点登录
  </Card>

  <Card title="OpenLDAP 集成" icon="server" href="/zh/on-call/integration/sso/openldap">
    通过 OpenLDAP 配置 Flashduty SSO 单点登录
  </Card>
</CardGroup>