单点登录管理

2026-11-17

单点登录(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 三种接入协议。

比较项OIDCSAML 2.0OAuth2
身份信息来源ID TokenSAML 断言(Assertion)User URL 返回的用户信息 JSON
配置入口Discovery URLIdP Metadata URL 或 Metadata XML 文件手工填写授权、Token 和用户信息端点
角色读取配置Role PathRole AttributeRole Path(UserInfo)
用户唯一标识issuer + subIdP Entity ID + persistent NameIDRealm + 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」,选择接入协议。

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

基本配置

  1. 填写 Realm 名称、展示名称及登录路由邮箱。
  2. 选择「IdP Metadata URL」或「上传 XML」,导入企业 IdP 的 Metadata。系统解析 IdP Entity ID、SSO URL、签名证书及 Binding。
  3. 保存草稿,获取系统生成的 SP Metadata URL、ACS URL,或下载 SP Metadata XML。
  4. 将司空 2 的 SP Metadata 提供给 IdP 管理员,配置对应的 SAML 应用。SP Entity ID 应从实际生成的 SP Metadata 中读取,不应假定其与 Metadata URL 相同。
  5. 在「授权管理」中填写角色属性名称,并完成管理角色映射。

采用 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 URLIdP 提供的用户授权地址
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 管理角色。

角色字段读取及管理角色映射

协议配置项要求
OIDCRole Path指向身份结果中的角色字符串数组,例如 roles
SAML 2.0Role Attribute与断言中的 Attribute Name 一致,例如 roles;多个角色使用多个 AttributeValue
OAuth2Role Path(UserInfo)指向 User URL 响应中的角色字符串数组,例如 data.roles

管理角色及默认映射如下,每个管理角色配置一个外部 Role 值:

司空 2 管理角色默认外部 Role 值优先级
组织管理员fh2-admin-org1(最高)
设备维护员fh2-admin-device2
组织成员fh2-member-org3
  • 用户至少匹配一个管理角色才能通过新建 SSO Realm 登录。
  • 同时匹配多个管理角色时,采用优先级最高的角色;未识别的 Role 值忽略。
  • 外部 SSO 用户不能映射为超级管理员。
  • 当前通过 Roles 授权,不直接通过 Groups、Security Groups 或其他属性授予权限。如企业使用群组管理人员,可在 IdP 中将群组关系转换为约定的角色列表。

项目权限

SSO 管理角色与项目权限相互独立。登录成功后,管理员仍需在项目成员管理中添加 SSO 用户、分配项目角色,并使用对应 Realm 的稳定唯一标识匹配用户。项目角色配置详见项目角色管理。



测试与启用

测试流程

  1. 完成基本配置和授权管理,点击「保存草稿」。
  2. 进入「测试与启用」,执行「连通性测试」,检查必填字段、HTTPS、协议端点,以及相应的 Discovery、Metadata 或证书配置。
  3. 执行「测试登录」,在打开的 IdP 页面使用测试账号完成认证,再返回原配置页面。
  4. 核对返回的稳定标识、显示名称、邮箱、Role 列表及管理角色,确认角色读取和映射符合预期。
  5. 测试通过后,点击「保存并生效」,确认身份源状态为已启用。
连通性测试与测试登录均通过的状态

连通性测试仅验证配置及端点,不能代替实际用户登录测试。OIDC 连通性测试是启用的必要条件;测试登录未通过时,按页面提示进行风险确认的启用方式不代表登录验证通过,建议完成两项测试后再启用。SAML 2.0 应完成两项测试后启用;新建 OAuth2 Realm 需两项测试均通过,不应仅根据按钮可点击或通用确认提示判断测试通过。

Discovery 读取、Metadata 导入或 Token 换取失败时,应核对司空 2 后端网络、TLS 证书信任、应用凭据、回调地址及协议参数,修正后重新保存和测试。


身份源维护

列表支持编辑或继续配置、测试、启用、停用及删除操作。身份源状态及对应处理方式如下:

状态处理方式
草稿补全配置,保存后执行测试
需重新测试核对关键配置变更,重新测试
测试失败查看失败结果,修正 IdP 或司空 2 配置后重新测试
可启用确认测试结果,按页面条件启用
已启用可用于登录;关键配置变更后按提示重新测试
已禁用保留配置,不作为正常登录入口

更新 IdP 的端点、证书或角色输出后,应同步更新 Realm 并重新测试。手工覆盖字段不会随自动读取结果更新,需单独核对。



本地账号登录管理

「SSO 登录设置」页面中的「允许本地账号密码登录」开关控制普通本地账号是否可使用密码登录。关闭后,普通本地账号无法使用密码登录,组织成员需通过已启用且通过测试的 SSO 身份源登录。

关闭步骤:

  1. 完成至少一个 Realm 的配置、测试和启用,并确认企业账号可正常登录。
  2. 确认可用的应急超级管理员账号及其本地密码。
  3. 关闭「允许本地账号密码登录」,在弹窗中选择「指定应急超级管理员」。
  4. 阅读影响说明,勾选确认项,点击「确认关闭」。
关闭本地账号登录时指定应急超级管理员

企业 IdP 不可用或 SSO 配置异常时,由指定的应急超级管理员使用本地密码进入系统,重新开启本地账号登录或修复 SSO 配置。普通组织管理员不等同于应急超级管理员,也不能仅根据账号名称判断其可使用应急登录。



Keycloak 对接示例

以下以 Keycloak 为例说明三种协议的配置方法。示例域名、Realm 名称、Client ID 和字段路径需替换为实际环境的值;回调地址及 SP Metadata 信息以司空 2 生成的结果为准。Keycloak 不同版本的菜单位置可能存在差异。

截图用于说明配置入口及关键选项,其中的 Realm、Client 和测试用户名称为示例值。实际配置时,请使用本企业的身份源、应用和用户信息。


创建企业身份源、角色和测试用户

  1. 登录 Keycloak 管理控制台,在「Manage realms / 管理领域」中创建或选择企业 Realm,例如 Enterprise。

    Keycloak 创建领域,填写领域名称并启用
  2. 在「Realm roles / 领域角色」中创建 fh2-admin-org、fh2-admin-device 和 fh2-member-org,或创建与司空 2 映射一致的角色值。

    Keycloak 领域角色列表及创建角色入口
  3. 在「Users / 用户管理」中创建并启用测试用户,在「Credentials / 凭证」中设置密码,完成该用户必需的账号操作。

  4. 在用户的「Role mapping / 角色映射」中分配测试角色。建议首次测试仅分配一种管理角色,例如 fh2-member-org,便于核对结果。

    Keycloak 用户角色映射,将组织成员角色分配给测试用户

Keycloak 中的企业 Realm 与司空 2 的 Realm 是不同的配置单元,不要求名称相同。对接多个协议时,应分别配置对应 Client,并使用不同的登录路由域名。


OIDC 对接

  1. 在 Keycloak 中创建「OpenID Connect」类型 Client,例如 Enterprise_OIDC。

  2. 开启 Client authentication 和 Standard flow,关闭 Implicit flow;浏览器 SSO 无需启用 Direct access grants。开启 Require PKCE,将 PKCE Method 设置为 S256。相应入口可在「Settings → Capability config」中查找。

    Keycloak 客户端认证流程及 PKCE S256 配置
  3. 在司空 2 新建 OIDC Realm,填写登录路由邮箱、Client ID、Client Secret 和 Discovery URL。Keycloak Discovery URL 的结构如下:

    https://idp.example.com/realms/Enterprise/.well-known/openid-configuration
    
  4. 保存司空 2 草稿,取得实际回调信息。在 Keycloak Client 的 Valid redirect URIs 中登记正式及测试回调地址,并根据司空 2 生成的信息填写 Web origins。Client Secret 从该 Client 的「Credentials」页获取。

  5. 在「Client scopes → 对应 Client 的 dedicated scope → Mappers」中添加 User Realm Role Mapper:

    进入「客户端范围 / Client scopes」,选择当前 Client 的「专用范围 / dedicated scope」,再进入映射器配置。

    Keycloak 客户端范围中的专用 Scope 入口
    配置项示例设置
    Namesikong-roles
    Token Claim Nameroles
    Claim JSON TypeString
    MultivaluedOn
    Add to ID token / Add to access token / Add to userinfoOn
    Keycloak User Realm Role 映射器,输出多值 roles 并添加到令牌和用户信息
  6. 在司空 2 将 Role Path 设置为 roles,完成管理角色映射,执行连通性测试和测试登录,核对角色后保存并生效。


SAML 2.0 对接

  1. 从 Keycloak 获取 IdP Metadata,地址结构如下。也可获取该地址返回的 Metadata XML,用于文件上传。

    https://idp.example.com/realms/Enterprise/protocol/saml/descriptor
    
  2. 在司空 2 新建 SAML 2.0 Realm,导入 IdP Metadata 并保存草稿,下载实际生成的 SP Metadata XML。

  3. 在 Keycloak 通过「Clients → Import client」导入 SP Metadata,或手工创建 SAML Client 并核对以下字段:

    配置项示例设置
    Client ID司空 2 SP Metadata 中的 Entity ID
    Name用于识别应用的名称,例如 Enterprise_SAML
    Valid redirect URIs司空 2 ACS URL
    Name ID formatpersistent
    Force name ID formatOn
    Force POST bindingOn,使用 POST 返回 SAML 响应
    Sign documents / Sign assertionsOn
    Signature algorithmRSA_SHA256
    Client signature requiredOn,从司空 2 SP Metadata 导入 SP 签名证书
    IDP-Initiated SSO URL name留空,从司空 2 发起登录

    下图展示 persistent NameID 和 POST Binding 的配置位置;签名与证书配置仍需按上表逐项核对。

    Keycloak SAML persistent NameID 及 POST Binding 配置
  4. 在该 SAML Client 的 dedicated scope 中配置角色及用户资料 Mapper:

    Mapper 类型关键配置
    Role listName 和 Role attribute name 为 roles,NameFormat 为 Basic,Single Role Attribute 为 On
    User PropertyUser property 为 username,Attribute name 为 displayName
    User PropertyUser property 为 email,Attribute name 为 email
    Keycloak SAML Role list 映射器,配置 roles 属性及 Single Role Attribute
  5. 核对该 Client 的默认 role_list scope 与自定义角色 Mapper,避免重复或冲突的角色输出。若采用上述自定义 roles Mapper,应移除该 Client 中冲突的默认 scope 分配。

  6. 在司空 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 协议。

  1. 在 Keycloak 新建独立 Client,例如 Enterprise_OAuth2,按上述 OIDC 示例配置 Client authentication、Standard flow、PKCE、正式及测试回调地址,并获取该 Client 的独立 Secret。

  2. 在该 Client 的 dedicated scope 中添加 User Realm Role Mapper,Token Claim Name 为 roles,Multivalued 为 On,确保 Add to userinfo 为 On。

  3. 在司空 2 新建 OAuth2 Realm,填写对应应用凭据、登录路由邮箱及以下配置:

    司空 2 字段Keycloak 示例
    Authorization URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/auth
    Token 地址https://idp.example.com/realms/Enterprise/protocol/openid-connect/token
    User URLhttps://idp.example.com/realms/Enterprise/protocol/openid-connect/userinfo
    USER_ID_KEYsub
    USER_ACCOUNT_KEYpreferred_username
    Scopesopenid profile email,用于本例 Keycloak 用户信息接口
    Role Path(UserInfo)roles
  4. 保存草稿,完成管理角色映射。连通性测试和测试登录均通过,且用户信息与管理角色符合预期后,再保存并生效。

示例中的 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 还需确认两项测试均通过。

Last Updated: