单点登录管理
单点登录(Single Sign-On,SSO)支持用户通过企业统一账号登录大疆司空 2。企业身份提供商(Identity Provider,IdP)负责验证用户身份,司空 2 根据返回的身份信息和角色映射建立登录会话并授予相应权限。企业账号的密码由企业身份系统管理。
本功能适用于公有云企业版套餐和私有化版本。本文面向组织管理员及企业身份系统管理员,介绍身份源配置、授权管理、测试与启用,以及本地账号登录管理。
功能概述
身份源与登录流程
Realm 是司空 2 中一条独立的 SSO 身份源配置。每个 Realm 使用一种协议,并根据邮箱域名匹配登录请求。企业 IdP 中对应的应用与司空 2 Realm 应使用一致的协议、应用凭据、回调地址和角色输出约定。
用户从司空 2 发起 SSO 登录后,系统根据输入邮箱的域名选择已启用的身份源,跳转至企业 IdP 完成身份验证,再验证返回的身份结果并匹配管理角色。企业登录会话过期或要求重新认证时,用户仍需在 IdP 完成认证。
邮箱域名仅用于选择身份源,不作为用户唯一标识,也不直接授予权限。SSO 登录后的项目访问权限需另行配置。
协议选择
司空 2 支持 OIDC、SAML 2.0 和 OAuth2 三种接入协议。
| 比较项 | OIDC | SAML 2.0 | OAuth2 |
|---|---|---|---|
| 身份信息来源 | ID Token | SAML 断言(Assertion) | User URL 返回的用户信息 JSON |
| 配置入口 | Discovery URL | IdP Metadata URL 或 Metadata XML 文件 | 手工填写授权、Token 和用户信息端点 |
| 角色读取配置 | Role Path | Role Attribute | Role Path(UserInfo) |
| 用户唯一标识 | issuer + sub | IdP Entity ID + persistent NameID | Realm + USER_ID_KEY 对应值 |
| 适用场景 | 支持 OpenID Connect 的企业身份系统 | 已采用 SAML 的企业身份系统 | 提供 OAuth2 授权及用户信息接口的系统 |
说明:
- 如果企业 IdP 支持多种协议,建议优先使用 OIDC;如果企业已通过 SAML 接入其他应用,也可以继续使用 SAML。
- OAuth2 属于授权协议,选择 OAuth2 时,需提前与 IdP 管理员确认用户信息接口中哪些字段用于提供稳定的用户 ID、账号名称和角色信息。
- OIDC 和 OAuth2 均采用授权码流程,并使用 PKCE 校验。两者获取身份信息的方式不同:
- OIDC:通过验证 ID Token 确认用户身份。
- OAuth2:使用 Access Token 调用 User URL,获取并解析用户信息,不使用 OIDC 的 ID Token、Discovery 或 JWKS 身份验证机制。
- SAML 2.0 仅支持从司空 2 发起的登录(SP-Initiated),不支持从企业 IdP 的应用门户直接发起。
配置准备
私有化版本必须先开启 HTTPS,才能使用单点登录功能。 请在部署环境中完成 HTTPS 配置,确认司空 2 可通过 HTTPS 访问后,再配置 SSO 身份源。
组织管理员进入对应组织的「SSO 登录设置」页面,点击「新建 Realm」,选择接入协议。

配置前,请与企业 IdP 管理员准备以下信息:
- 所采用的协议,以及对应应用的 Client ID、Client Secret 或 Metadata。
- 用于匹配身份源的邮箱域名,以及可用于测试登录的企业账号。
- 企业身份结果中的角色字段、角色值,以及需要授予的司空 2 管理角色。
- IdP 的 HTTPS 端点及有效证书,确保司空 2 后端可访问相关端点并验证其证书。
配置规则:
- 同一组织最多同时启用 8 个 Realm。未启用的配置可保存为草稿,或保留为停用状态。
- Realm 名称在组织内唯一;展示名称用于后台展示和识别。
- 新建时,「登录路由邮箱」可以是完整有效的邮箱或仅域名,例如
user@example.com。系统保存其域名进行登录路由,同一组织内不得将同一域名配置给不同 Realm。 - 司空 2 访问地址及 SSO 端点使用 HTTPS。系统生成的回调信息应原样登记至 IdP,不使用配置页面地址替代回调地址。
身份源配置
每个 Realm 的配置页面包含「基本配置」「授权管理」「测试与启用」和「高级配置」四个页签。先完成基本配置并保存草稿,再配置角色映射、执行测试并启用。
OIDC
基本配置
| 字段 | 填写说明 |
|---|---|
| Realm 名称 / 展示名称 | 填写用于识别身份源的名称,例如 Enterprise_OIDC |
| 登录路由邮箱 | 填写完整邮箱,其域名用于选择身份源 |
| Discovery URL | 填写 IdP 提供的完整 HTTPS Discovery 地址 |
| Client ID | 填写在 IdP 中注册的应用标识 |
| Client Secret | 填写对应应用的密钥;保存后不回显明文 |
| Callback URL | 保存草稿后由系统生成,原样登记为 IdP 的有效重定向地址 |
| Web Origin URL | 由系统生成,按 IdP 要求登记至 Web Origins |
保存草稿后,复制本环境的实际回调信息并完成 IdP 应用配置。新建表单中的占位地址不能用于实际对接。正式登录与「测试登录」可能使用不同的回调地址,应按实际部署分别登记。
在「授权管理」中,根据 IdP 返回的角色数组填写 Role Path,例如 roles 或 claims.roles。角色映射规则见下文「授权管理」。
高级配置
- 身份唯一标识:固定为
issuer + sub,不支持改为邮箱。 - 用户显示名 Claim:默认
name,仅用于显示和搜索,不参与身份匹配或权限授予。 - Discovery 刷新:首次读取后默认不自动刷新,可使用「立即刷新」重新获取。刷新失败时保留最近有效配置;自动刷新及间隔设置以当前部署提供的配置项为准。
- 协议高级项:可配置 Scope,至少包含
openid;可手工覆盖 Authorization Endpoint、Token Endpoint 和 JWKS URI。 - 手工覆盖:覆盖字段不会随 Discovery 刷新改写;点击「恢复自动值」可恢复发现结果。手工覆盖不能替代保存配置时对 Discovery 的读取与校验。
SAML 2.0
基本配置
- 填写 Realm 名称、展示名称及登录路由邮箱。
- 选择「IdP Metadata URL」或「上传 XML」,导入企业 IdP 的 Metadata。系统解析 IdP Entity ID、SSO URL、签名证书及 Binding。
- 保存草稿,获取系统生成的 SP Metadata URL、ACS URL,或下载 SP Metadata XML。
- 将司空 2 的 SP Metadata 提供给 IdP 管理员,配置对应的 SAML 应用。SP Entity ID 应从实际生成的 SP Metadata 中读取,不应假定其与 Metadata URL 相同。
- 在「授权管理」中填写角色属性名称,并完成管理角色映射。
采用 URL 导入时,Metadata 地址需可被司空 2 后端通过 HTTPS 访问。采用文件上传时,应使用企业 IdP 实际导出的 Metadata XML。
Role Attribute 填写 SAML 断言中 <Attribute Name="..."> 的准确名称,默认 roles,区分大小写。多个角色应通过多个 AttributeValue 返回,不应合并为一个字符串。例如:
<Attribute Name="roles">
<AttributeValue>fh2-member-org</AttributeValue>
</Attribute>
高级配置
- 身份唯一标识:固定为
IdP Entity ID + persistent NameID,IdP 应配置 persistent NameID。 - 用户显示名 Attribute:默认
displayName,需由 IdP 实际输出。 - Metadata 更新:首次读取后默认不自动刷新。URL 导入模式可通过页面提供的刷新入口更新;XML 上传模式需重新上传文件。自动刷新及间隔设置以当前部署提供的配置项为准。
- 协议高级项:可手工覆盖 IdP Entity ID、SSO URL、Binding 和签名证书,或恢复自动值。手工覆盖字段不会被 Metadata 刷新改写。
- 证书管理:建议通过 Metadata 导入和更新签名证书。证书指纹用于核对证书,不能代替 X.509 证书正文。
OAuth2
基本配置
OAuth2 不使用 Discovery,需根据 IdP 的接口文档填写端点及用户信息字段路径。
| 字段 | 填写说明 |
|---|---|
| Realm 名称 / 展示名称 | 填写身份源名称,例如 Enterprise_OAuth2 |
| 登录路由邮箱 | 填写完整邮箱,其域名用于选择身份源 |
| Authorization URL | IdP 提供的用户授权地址 |
| Token 地址 | IdP 提供的授权码兑换地址 |
| User URL | 使用 Access Token 获取用户身份及角色 JSON 的接口地址 |
| Client ID / Client Secret | 对应 IdP 应用的标识及密钥 |
| USER_ID_KEY | 用户信息响应中稳定用户 ID 的字段路径,例如 id 或 data.id |
| USER_ACCOUNT_KEY | 用户信息响应中账号名称的字段路径,例如 username 或 data.username |
| Scopes | 按 IdP 用户信息接口的权限要求配置 |
| Callback URL | 保存草稿后由系统生成,原样登记至 IdP |
在「授权管理」中,Role Path(UserInfo)应指向 User URL 响应中的角色字符串数组,例如 roles 或 data.roles。司空 2 不从 JWT Access Token 或独立权限接口读取 OAuth2 角色。
例如,User URL 返回以下结构时,USER_ID_KEY 填写 id,USER_ACCOUNT_KEY 填写 username,Role Path 填写 roles:
{
"id": "user-001",
"username": "sso-user",
"roles": ["fh2-member-org"]
}
上述字段仅为结构示例,实际字段路径应与 IdP 响应一致。Scopes 不决定角色,也不统一要求包含 openid;应遵循 IdP 的接口要求。即使 USER_ID_KEY 使用 sub,或 Scopes 包含 openid,此 Realm 仍按 OAuth2 用户信息接口解析身份与角色。
高级配置
「高级配置」展示 USER_ID_KEY 对应的稳定身份规则及用户显示名字段路径。显示信息沿用 USER_ACCOUNT_KEY,无需另行配置第二条字段路径。
OAuth2 不提供 Discovery 或 Metadata 导入及刷新功能,端点变更后需手工更新。新建 Realm 不提供旧配置中的 USE_REDIRECT_URL、SUPER_ACCOUNT 兼容项;历史迁移配置的兼容权限行为不适用于新建 Realm。
授权管理
角色读取与管理角色映射
在「授权管理」中设置角色读取位置,并将 IdP 返回的外部 Role 值映射为司空 2 管理角色。

| 协议 | 配置项 | 要求 |
|---|---|---|
| OIDC | Role Path | 指向身份结果中的角色字符串数组,例如 roles |
| SAML 2.0 | Role Attribute | 与断言中的 Attribute Name 一致,例如 roles;多个角色使用多个 AttributeValue |
| OAuth2 | Role Path(UserInfo) | 指向 User URL 响应中的角色字符串数组,例如 data.roles |
管理角色及默认映射如下,每个管理角色配置一个外部 Role 值:
| 司空 2 管理角色 | 默认外部 Role 值 | 优先级 |
|---|---|---|
| 组织管理员 | fh2-admin-org | 1(最高) |
| 设备维护员 | fh2-admin-device | 2 |
| 组织成员 | fh2-member-org | 3 |
- 用户至少匹配一个管理角色才能通过新建 SSO Realm 登录。
- 同时匹配多个管理角色时,采用优先级最高的角色;未识别的 Role 值忽略。
- 外部 SSO 用户不能映射为超级管理员。
- 当前通过 Roles 授权,不直接通过 Groups、Security Groups 或其他属性授予权限。如企业使用群组管理人员,可在 IdP 中将群组关系转换为约定的角色列表。
项目权限
SSO 管理角色与项目权限相互独立。登录成功后,管理员仍需在项目成员管理中添加 SSO 用户、分配项目角色,并使用对应 Realm 的稳定唯一标识匹配用户。项目角色配置详见项目角色管理。
测试与启用
测试流程
- 完成基本配置和授权管理,点击「保存草稿」。
- 进入「测试与启用」,执行「连通性测试」,检查必填字段、HTTPS、协议端点,以及相应的 Discovery、Metadata 或证书配置。
- 执行「测试登录」,在打开的 IdP 页面使用测试账号完成认证,再返回原配置页面。
- 核对返回的稳定标识、显示名称、邮箱、Role 列表及管理角色,确认角色读取和映射符合预期。
- 测试通过后,点击「保存并生效」,确认身份源状态为已启用。

连通性测试仅验证配置及端点,不能代替实际用户登录测试。OIDC 连通性测试是启用的必要条件;测试登录未通过时,按页面提示进行风险确认的启用方式不代表登录验证通过,建议完成两项测试后再启用。SAML 2.0 应完成两项测试后启用;新建 OAuth2 Realm 需两项测试均通过,不应仅根据按钮可点击或通用确认提示判断测试通过。
Discovery 读取、Metadata 导入或 Token 换取失败时,应核对司空 2 后端网络、TLS 证书信任、应用凭据、回调地址及协议参数,修正后重新保存和测试。
身份源维护
列表支持编辑或继续配置、测试、启用、停用及删除操作。身份源状态及对应处理方式如下:
| 状态 | 处理方式 |
|---|---|
| 草稿 | 补全配置,保存后执行测试 |
| 需重新测试 | 核对关键配置变更,重新测试 |
| 测试失败 | 查看失败结果,修正 IdP 或司空 2 配置后重新测试 |
| 可启用 | 确认测试结果,按页面条件启用 |
| 已启用 | 可用于登录;关键配置变更后按提示重新测试 |
| 已禁用 | 保留配置,不作为正常登录入口 |
更新 IdP 的端点、证书或角色输出后,应同步更新 Realm 并重新测试。手工覆盖字段不会随自动读取结果更新,需单独核对。
本地账号登录管理
「SSO 登录设置」页面中的「允许本地账号密码登录」开关控制普通本地账号是否可使用密码登录。关闭后,普通本地账号无法使用密码登录,组织成员需通过已启用且通过测试的 SSO 身份源登录。
关闭步骤:
- 完成至少一个 Realm 的配置、测试和启用,并确认企业账号可正常登录。
- 确认可用的应急超级管理员账号及其本地密码。
- 关闭「允许本地账号密码登录」,在弹窗中选择「指定应急超级管理员」。
- 阅读影响说明,勾选确认项,点击「确认关闭」。

企业 IdP 不可用或 SSO 配置异常时,由指定的应急超级管理员使用本地密码进入系统,重新开启本地账号登录或修复 SSO 配置。普通组织管理员不等同于应急超级管理员,也不能仅根据账号名称判断其可使用应急登录。
Keycloak 对接示例
以下以 Keycloak 为例说明三种协议的配置方法。示例域名、Realm 名称、Client ID 和字段路径需替换为实际环境的值;回调地址及 SP Metadata 信息以司空 2 生成的结果为准。Keycloak 不同版本的菜单位置可能存在差异。
截图用于说明配置入口及关键选项,其中的 Realm、Client 和测试用户名称为示例值。实际配置时,请使用本企业的身份源、应用和用户信息。
创建企业身份源、角色和测试用户
登录 Keycloak 管理控制台,在「Manage realms / 管理领域」中创建或选择企业 Realm,例如
Enterprise。
在「Realm roles / 领域角色」中创建
fh2-admin-org、fh2-admin-device和fh2-member-org,或创建与司空 2 映射一致的角色值。
在「Users / 用户管理」中创建并启用测试用户,在「Credentials / 凭证」中设置密码,完成该用户必需的账号操作。
在用户的「Role mapping / 角色映射」中分配测试角色。建议首次测试仅分配一种管理角色,例如
fh2-member-org,便于核对结果。
Keycloak 中的企业 Realm 与司空 2 的 Realm 是不同的配置单元,不要求名称相同。对接多个协议时,应分别配置对应 Client,并使用不同的登录路由域名。
OIDC 对接
在 Keycloak 中创建「OpenID Connect」类型 Client,例如
Enterprise_OIDC。开启 Client authentication 和 Standard flow,关闭 Implicit flow;浏览器 SSO 无需启用 Direct access grants。开启 Require PKCE,将 PKCE Method 设置为
S256。相应入口可在「Settings → Capability config」中查找。
在司空 2 新建 OIDC Realm,填写登录路由邮箱、Client ID、Client Secret 和 Discovery URL。Keycloak Discovery URL 的结构如下:
https://idp.example.com/realms/Enterprise/.well-known/openid-configuration保存司空 2 草稿,取得实际回调信息。在 Keycloak Client 的 Valid redirect URIs 中登记正式及测试回调地址,并根据司空 2 生成的信息填写 Web origins。Client Secret 从该 Client 的「Credentials」页获取。
在「Client scopes → 对应 Client 的 dedicated scope → Mappers」中添加 User Realm Role Mapper:
进入「客户端范围 / Client scopes」,选择当前 Client 的「专用范围 / dedicated scope」,再进入映射器配置。

配置项 示例设置 Name sikong-rolesToken Claim Name rolesClaim JSON Type StringMultivalued On Add to ID token / Add to access token / Add to userinfo On 
在司空 2 将 Role Path 设置为
roles,完成管理角色映射,执行连通性测试和测试登录,核对角色后保存并生效。
SAML 2.0 对接
从 Keycloak 获取 IdP Metadata,地址结构如下。也可获取该地址返回的 Metadata XML,用于文件上传。
https://idp.example.com/realms/Enterprise/protocol/saml/descriptor在司空 2 新建 SAML 2.0 Realm,导入 IdP Metadata 并保存草稿,下载实际生成的 SP Metadata XML。
在 Keycloak 通过「Clients → Import client」导入 SP Metadata,或手工创建 SAML Client 并核对以下字段:
配置项 示例设置 Client ID 司空 2 SP Metadata 中的 Entity ID Name 用于识别应用的名称,例如 Enterprise_SAMLValid redirect URIs 司空 2 ACS URL Name ID format persistentForce name ID format On Force POST binding On,使用 POST 返回 SAML 响应 Sign documents / Sign assertions On Signature algorithm RSA_SHA256Client signature required On,从司空 2 SP Metadata 导入 SP 签名证书 IDP-Initiated SSO URL name 留空,从司空 2 发起登录 下图展示 persistent NameID 和 POST Binding 的配置位置;签名与证书配置仍需按上表逐项核对。

在该 SAML Client 的 dedicated scope 中配置角色及用户资料 Mapper:
Mapper 类型 关键配置 Role list Name 和 Role attribute name 为 roles,NameFormat 为Basic,Single Role Attribute 为 OnUser Property User property 为 username,Attribute name 为displayNameUser Property User property 为 email,Attribute name 为email
核对该 Client 的默认
role_listscope 与自定义角色 Mapper,避免重复或冲突的角色输出。若采用上述自定义rolesMapper,应移除该 Client 中冲突的默认 scope 分配。在司空 2 将 Role Attribute 设置为
roles,用户显示名 Attribute 设置为displayName,完成管理角色映射。两项测试通过后保存并生效。
Client ID 必须使用实际 SP Entity ID,不能用应用展示名称替代。司空 2 的 AuthnRequest 可采用 Redirect Binding,IdP 的响应采用 POST Binding,两者用途不同。重建司空 2 SAML Realm 后,应重新获取 SP Metadata,核对并更新 IdP 中的 Entity ID、ACS 和证书配置。
OAuth2 对接
Keycloak 使用「OpenID Connect」类型 Client 提供 OAuth2 端点,司空 2 侧仍选择 OAuth2 协议。
在 Keycloak 新建独立 Client,例如
Enterprise_OAuth2,按上述 OIDC 示例配置 Client authentication、Standard flow、PKCE、正式及测试回调地址,并获取该 Client 的独立 Secret。在该 Client 的 dedicated scope 中添加 User Realm Role Mapper,Token Claim Name 为
roles,Multivalued 为 On,确保 Add to userinfo 为 On。在司空 2 新建 OAuth2 Realm,填写对应应用凭据、登录路由邮箱及以下配置:
司空 2 字段 Keycloak 示例 Authorization URL https://idp.example.com/realms/Enterprise/protocol/openid-connect/authToken 地址 https://idp.example.com/realms/Enterprise/protocol/openid-connect/tokenUser URL https://idp.example.com/realms/Enterprise/protocol/openid-connect/userinfoUSER_ID_KEY subUSER_ACCOUNT_KEY preferred_usernameScopes openid profile email,用于本例 Keycloak 用户信息接口Role Path(UserInfo) roles保存草稿,完成管理角色映射。连通性测试和测试登录均通过,且用户信息与管理角色符合预期后,再保存并生效。
示例中的 Scopes 和用户字段适用于上述 Keycloak 配置,接入其他 IdP 时应依据其接口文档调整。
常见问题
连通性测试通过,为什么用户仍无法登录?
连通性测试检查配置和端点,测试登录才验证实际身份、角色读取与管理角色映射。请执行测试登录,检查稳定用户 ID、角色字段、映射结果、回调地址及签名验证结果。
提示回调地址不匹配,如何处理?
将实际请求中的 redirect_uri 与 IdP 对应应用登记的回调地址精确比对,包括协议、域名、端口和路径。正式登录和配置测试的回调均需按实际部署登记,不能使用前端配置页面地址或未保存表单的占位值。
登录路由邮箱必须与 IdP 用户邮箱一致吗?
登录路由邮箱用于选择身份源,IdP 用户邮箱属于用户资料,两者用途不同。账号与邮箱要求应遵循 IdP 配置。登录路由域名应符合邮箱格式要求,不使用带下划线的域名;新建时填写完整邮箱。
为什么无法读取 IdP 返回的角色?
OIDC 应核对 Role Path 与身份结果中的数组结构;OAuth2 应核对 User URL 返回的角色数组;SAML 应核对 Attribute Name 的大小写及多个 AttributeValue 的输出方式。同时检查 IdP 默认 Mapper 与自定义 Mapper 是否冲突,并确认返回的 Role 值与管理角色映射一致。
登录成功后为什么看不到项目?
SSO 管理角色不自动授予项目权限。管理员需在项目成员管理中添加对应用户并分配项目角色,使用其所属 Realm 的稳定唯一标识进行匹配。
可以使用邮箱作为用户唯一标识吗?
不支持。邮箱可能变更或被复用。OIDC 使用 issuer + sub,SAML 使用 IdP Entity ID + persistent NameID,OAuth2 使用 Realm + 稳定用户 ID。用户显示名和账号名称也不替代稳定唯一标识。
读取 Discovery 或 Metadata 失败,如何处理?
检查地址是否正确、司空 2 后端是否可访问该 HTTPS 地址,以及后端是否信任 IdP 证书。浏览器可访问或接受证书不代表司空 2 后端可访问并信任该证书。SAML 也可使用 IdP 实际导出的 Metadata XML 上传配置。修复后重新保存并测试。
IdP 认证完成后提示 Token 换取失败,如何处理?
检查司空 2 后端到 Token 地址的网络和 TLS 证书信任,并核对对应 Client 的 ID、Secret、实际回调地址及 PKCE 参数。修复后重新测试,确认用户信息及管理角色读取成功。
证书或端点变更后如何更新?
OIDC 可刷新 Discovery;SAML URL 导入模式可刷新 Metadata,XML 上传模式需重新上传文件。核对手工覆盖字段,必要时更新或恢复自动值。OAuth2 需手工修改端点。更新后重新执行测试。
退出司空 2 会同时退出企业 IdP 吗?
退出操作仅结束司空 2 登录会话,不联动退出企业 IdP。再次登录时,企业会话可能仍然有效;测试登录也可能要求重新认证。
关闭本地密码登录后,IdP 故障时如何恢复?
由关闭时指定的应急超级管理员使用本地密码进入系统,重新开启本地账号登录或修复 SSO。关闭前应确认该账号及密码可用。
身份源无法启用,如何处理?
检查草稿是否已保存、必填字段是否有效、是否提示重新测试,以及是否达到 8 个已启用 Realm 的上限。新建 OAuth2 Realm 还需确认两项测试均通过。