单点登录-自定义集成对接

本文介绍如何通过自定义集成对接功能实现单点登录，适用于目标应用不支持标准 SSO 协议（OIDC、SAML、OAUTH2、CAS）的场景。

概述

自定义集成对接功能支持通过链接流编排的方式实现单点登录。当目标应用系统不支持标准单点登录协议时，如果满足以下条件，即可通过链接流搭建单点登录：

目标系统具备单点登录 URL 地址，支持通过 URL 参数传递认证信息

目标系统提供 API 接口，可以获取单点登录所需的 token、签名等凭证

目标系统能够通过 URL 参数或 token 中的信息识别用户身份

核心能力

调用目标系统的 API 接口获取认证凭证

将集成平台的用户信息映射到目标系统所需的格式

拼接生成符合目标系统要求的单点登录 URL

支持 URL 参数透传，可根据参数动态调整 SSO 逻辑

与标准协议的区别

协议	适用场景	配置复杂度
OIDC	支持 OpenID Connect 的应用	低
SAML 2.0	支持 SAML 2.0 的应用	低
OAuth 2.0	支持 OAuth 2.0 的应用	低
CAS	支持 CAS 协议的应用	低
自定义集成对接	不支持标准协议的应用	高

建议：如果目标系统支持标准协议，建议优先使用标准协议配置，更加简单、稳定、安全性更高。

前提条件

在开始配置前，需要从目标系统技术文档或技术支持获取以下信息：

关键信息	说明	是否必需	示例
单点登录 URL 地址	目标系统的单点登录入口地址	必需	`https://example.com/sso/login`
URL 参数格式	单点登录 URL 需要传递的参数	必需	`?token=xxx&user=xxx`
Token 获取接口	获取 token/签名的 API 接口地址	必需	`POST /api/sso/getToken`
Token 获取参数	调用 token 接口需要的参数	必需	`appId`, `appSecret`
用户标识字段	目标系统识别用户的字段	必需	`username`, `email`
认证方式	Token 的认证方式	必需	Bearer Token、请求头
接口调用凭证	调用 API 需要的凭证	必需	`appId`, `appSecret`
域名/租户信息	企业域名或租户标识	可选	`domain=abc.com`

不适用情况

以下情况不支持使用自定义集成对接：

目标系统没有提供单点登录 URL 地址

单点登录必须通过表单提交或复杂的 JavaScript 交互完成

无法通过 API 获取单点登录所需的 token 或签名

单点登录需要用户手动输入密码或进行二次验证

操作步骤

步骤 1：创建应用并配置

创建应用

在数犀集成平台创建应用，配置基本信息和登录方式

配置登录信息

配置应用的基本登录信息和认证方式

步骤 2：选择自定义集成对接协议

进入单点登录配置

在应用配置中找到单点协议选择区域

选择协议

选择「自定义集成对接」选项

重要：自定义集成对接功能适用于不支持标准单点登录协议的应用系统。

访问地址说明：
支持在 URL 后追加自定义参数，如 ?param1=value1&param2=value2，参数将通过 customParams 字段传递到连接流触发节点。

步骤 3：进入流程编排

点击流程编排

点击「进入流程编排」按钮，进入链接流编排页面

步骤 4：配置 Webhook 节点

Webhook 节点是流程的起始节点，当用户完成身份认证后，会自动触发该节点，输出用户的所有信息。

输出示例：

{
  "hook_url": "https://example.com/acm/flows/start/v2/1/xxx/xxx",
  "sync": true,
  "type": "同步",
  "value": {
    "sub": "用户唯一标识",
    "name": "用户姓名",
    "phone_number": "手机号",
    "email": "用户邮箱",
    "username": "用户名"
  },
  "customParams": {
    "param1": "value1",
    "param2": "value2"
  }
}

关键字段说明：

字段	类型	说明
value	Object	用户身份信息
value.username	String	用户名，通常用于匹配目标系统的用户标识
value.email	String	用户邮箱，可用于提取账号名和域名
value.name	String	用户姓名
value.sub	String	用户唯一标识
customParams	Object	自定义参数对象，包含 URL 中所有 query 参数

customParams 参数解析规则

场景	URL 示例	customParams 值
无参数	`/login`	`{}`
单个参数	`/login?code=ERP`	`{"code": "ERP"}`
多个参数	`/login?code=ERP&env=prod`	`{"code": "ERP", "env": "prod"}`
同名参数	`/login?id=1&id=2`	`{"id": ["1", "2"]}`
参数值含特殊字符	`/login?name=%E5%BC%A0%E4%B8%89`	`{"name": "张三"}`

步骤 5：配置 HTTP 节点

HTTP 节点用于调用目标系统的 API 接口，获取单点登录所需的凭证。

配置要点：

配置项	说明
请求方式	根据目标系统 API 文档选择 GET 或 POST
请求 URL	填写目标系统提供的 API 接口地址
请求头	配置必要的请求头（如 Content-Type、认证 token 等）
请求体	根据 API 文档配置请求参数
响应处理	从响应中提取所需字段，保存为流程变量供后续节点使用

提示：如果目标系统需要先获取 token，再使用 token 调用签名接口，则需要配置两个 HTTP 节点。

步骤 6：配置流程变量节点

流程变量节点用于将获取到的参数拼接成最终的单点登录 URL。

URL 拼接格式：

{单点登录入口地址}?{参数1}={值1}&{参数2}={值2}&...

配置要点：

从 HTTP 节点的响应中提取所需的参数（如 token、sign、endpoint 等）

从 Webhook 节点中提取用户信息（如用户名、邮箱等）

按照目标系统要求的格式拼接 URL

返回包含 url 字段的 JSON 对象

返回结果格式：

{
  "url": "https://example.com/sso/login?token=xxx&user=xxx"
}

步骤 7：连接节点并启用

按照以下顺序连接各个节点：

Webhook节点 → HTTP节点1 → HTTP节点2（如需要）→ 流程变量节点

保存配置

确保每个节点的输出能够正确传递给下一个节点后，保存配置

启用流程

启用同步流，使配置生效

用户关联配置

账号匹配规则

单点登录需要确保集成平台的用户账号与目标系统的账号能够正确匹配：

确认目标系统使用什么字段识别用户（用户名、邮箱、工号等）

确认该字段是否可以从集成平台的用户信息中获取

确保集成平台中的用户标识与目标系统中的账号名一致

用户信息映射

如果集成平台用户信息中的某个字段与目标系统的用户标识一致，可直接使用

如果使用邮箱地址，可能需要从 email 字段中提取账号前缀部分（@符号前的部分）

确保提取的账号名与目标系统中的实际账号名完全匹配

验证效果

配置完成后，用户访问应用的单点登录地址，完成身份认证后，系统将自动执行以下流程：

触发 Webhook

Webhook 节点输出用户信息

获取凭证

调用目标系统 API 接口获取单点登录凭证

生成 URL

拼接生成单点登录 URL

完成跳转

自动跳转到目标系统，用户无需再次登录

常见问题

Q：单点登录失败如何排查？

Q：如何确保账号匹配正确？

Q：API 调用顺序有什么要求？

配置注意事项

参数安全：API 接口的调用凭证等敏感参数应妥善保管，建议在流程编排中使用变量配置，避免硬编码。

URL 拼接：确保 URL 参数正确获取，注意 URL 参数的编码格式，验证拼接后的 URL 格式是否符合目标系统的要求。

附录

术语解释

术语	说明
自定义集成对接	通过链接流编排的方式实现非标准协议的单点登录
链接流编排	通过可视化方式配置流程节点，实现数据流转和处理逻辑
Webhook 节点	流程的起始节点，接收用户认证后的用户信息
HTTP 节点	用于调用外部 API 接口的节点
流程变量节点	用于处理数据并返回结果的节点

自定义集成单点登录配置说明

单点登录-自定义集成对接#

概述#

核心能力#

与标准协议的区别#

前提条件#

不适用情况#

操作步骤#

步骤 1：创建应用并配置#

步骤 2：选择自定义集成对接协议#

步骤 3：进入流程编排#

步骤 4：配置 Webhook 节点#

customParams 参数解析规则#

步骤 5：配置 HTTP 节点#

步骤 6：配置流程变量节点#

步骤 7：连接节点并启用#

用户关联配置#

账号匹配规则#

用户信息映射#

验证效果#

常见问题#

配置注意事项#

附录#

术语解释#