本文面向身份集成实施人员，说明如何将身份数据跨系统流转目标拆成可配置、可测试、可回退的实施阶段。完成后应能证明数据从来源进入目标系统，并能定位失败对象。本文按 6.7.1 系列固定源码基线整理。由于当前仓库没有独立的 6.7.1.1 Tag，正式发布前还需核对实际构建版本，并在目标租户完成运行验证。
场景与目标#
以一个可追踪的身份数据对象完成跨系统闭环：明确来源、转换、目标、失败处置和成功证据。适用条件#
已获得目标系统接口、网络、鉴权、字段与错误响应资料。
方案设计#
将连接流拆为触发、读取、转换、写入、返回和完成阶段。每个阶段只承担一个明确职责，并保留对象唯一键、任务 ID 和错误信息，便于幂等重试和审计。实施阶段#
先使用单个测试用户和部门完成节点级测试，再执行整流测试；只有返回结构、关系和日志均符合预期后才扩大范围。集成平台的身份自动化集成功能允许企业通过REST API方式与任意外部身份系统建立连接，实现灵活的身份数据同步。本指南详细说明如何配置REST API身份自动化集成。新版本对身份自动化集成进行了全面优化，将原有的外层参数配置整合到画布中，实现一站式闭环配置。用户可以在画布中完成所有配置工作，无需在多个页面间切换，大大提升了配置效率和使用体验。
新旧版本完整配置对照表#
基本信息配置对照#
| 旧版配置项 | 旧版位置 | 对应新版本位置 | 配置区域/ 配置项说明 |
|---|
| 名称 | 基本信息表单 | 画布导航栏顶部 | 名称编辑区域 |
| 数据在本地挂载节点 | 基本信息表单 | 创建或更新部门/用户节点 | 默认挂载节点 |
| 挂载方式 | 基本信息表单 | 创建或更新部门/用户节点 | 挂载方式 |
| 上游部门ID字段 | 基本信息表单 | 映射管理面板 | 部门Tab |
| 上游部门名称字段 | 基本信息表单 | 映射管理面板 | 部门Tab |
| 上游父部门ID字段 | 基本信息表单 | 映射管理面板 | 部门Tab |
| 上游用户ID字段 | 基本信息表单 | 映射管理面板 | 用户Tab |
| 上游用户所属部门字段 | 基本信息表单 | 映射管理面板 | 用户Tab |
属性映射配置对照#
| 旧版配置项 | 旧版位置 | 对应新版本位置 | 配置区域/ 配置项说明 |
|---|
| 用户信息字段映射 | 属性映射配置页 | 映射管理面板 | 用户Tab |
| 部门信息字段映射 | 属性映射配置页 | 映射管理面板 | 部门Tab |
| 角色信息字段映射 | 属性映射配置页 | 映射管理面板 | 角色Tab |
同步策略配置对照#
| 旧版配置项 | 旧版位置 | 对应新版本位置 | 配置区域/ 配置项说明 |
|---|
| 同步方式 | 同步策略配置页 | 通讯录集成Trigger节点 | 集成触发方式 |
| 同步周期 | 同步策略配置页 | 通讯录集成Trigger节点 | 触发周期 |
| 开始时间 | 同步策略配置页 | 通讯录集成Trigger节点 | 启用后即开始执行 |
| 账号关联 | 同步策略配置页 | 集成用户节点 | 账号关联设置 |
| 待删除用户阈值 | 同步策略配置页 | 完成通讯录集成节点 | 待删除用户阈值 |
配置流程对比#
旧版配置流程#
1. 新建连接器 → 2. 填写基本信息 → 3. 配置属性映射 → 4. 配置同步策略 → 5. 进入流程编排
新版配置流程#
1. 选择模板 → 2. 直接进入画布 → 3. 在画布中完成所有配置（映射管理、节点配置）
集成优势#
通用性强：可连接任何提供REST API的身份系统或应用
适用场景#
自建系统对接：连接企业内部自建的HR系统或业务系统
SaaS应用集成：同步来自SaaS应用的用户和组织数据
混合数据源整合：组合多个REST API数据源的用户信息
特殊格式处理：需要对API返回数据进行复杂转换的场景
定制化同步逻辑：需要特定业务规则处理的身份同步场景
准备工作#
必要条件#
确认网络环境允许集成平台访问目标API（如防火墙配置、IP白名单等）
API接口准备清单#
| API类型 | 接口地址 | 请求方法 | 认证方式 | 功能说明 | 是否必需 |
|---|
| 认证接口 | 例：/api/token | POST | Basic Auth | 获取访问令牌 | 视API而定 |
| 部门列表接口 | 例：/api/departments | GET | Bearer Token | 获取所有部门 | 是 |
| 部门详情接口 | 例：/api/departments/{id} | GET | Bearer Token | 获取单个部门详情 | 可选 |
| 用户列表接口 | 例：/api/users | GET | Bearer Token | 获取所有用户 | 是 |
| 用户详情接口 | 例：/api/users/{id} | GET | Bearer Token | 获取单个用户详情 | 可选 |
| 角色列表接口 | 例：/api/roles | GET | Bearer Token | 获取所有角色 | 可选 |
请根据您的实际API情况填写上表，并准备好接口的请求参数和响应数据示例，这将有助于后续的集成配置。新建身份集成流#
1.
登录云身份连接器平台，在左侧导航栏选择 "用户中心 > 通讯录集成"
3.
在模板选择页面，选择 "REST API 身份自动化模板"
4.
选择模板后将直接跳转至身份集成流画布，无需进行前置的参数配置
身份集成流画布配置#
新版本将所有配置项整合到画布中，提供了更加直观和便捷的配置体验。画布功能区域说明#
| 区域 | 功能说明 |
|---|
| 顶部导航栏 | 包含流程名称编辑、映射管理、保存、启用、重置等操作按钮 |
| 画布区域 | 可视化流程编排区域，用于配置各类节点 |
| Trigger节点 | 固定的触发节点，根据集成类型自动设置，不可删除 |
操作按钮#
| 按钮 | 功能说明 |
|---|
| 映射管理 | 打开属性映射配置面板，配置上游系统与集成平台的字段映射关系 |
| 保存 | 保存当前画布配置 |
| 启用/停用 | 启用或停用当前集成流 |
| 重置 | 重置画布配置到初始状态 |
映射管理配置#
点击顶部「映射管理」按钮，将打开属性映射配置面板。这是配置数据字段映射关系的核心功能。映射管理面板功能#
| 功能项 | 说明 |
|---|
| Tab切换 | 支持在「用户」和「部门」两个Tab间切换，分别配置不同类型的属性映射 |
| 上游系统字段 | 下拉选择当前集成流的扩展属性字段，支持「新增属性」功能 |
| IDAAS系统字段 | 下拉选择当前集成平台的系统字段，支持「新增属性」功能 |
| 添加映射 | 点击添加新的映射关系 |
| JS表达式 | 支持在输入框中编写JS表达式进行字段转换 |
映射配置规则#
1.
唯一性校验：同一IDAAS字段不允许配置多个映射关系
2.
JS表达式支持：选择字段后，可在输入框中编写JS表达式进行数据转换
3.
双向同步：配置完成并保存后，配置信息将与属性管理配置双向同步
通讯录集成Trigger节点配置#
集成触发方式#
| 触发方式 | 说明 | 适用场景 |
|---|
| 手动触发 | 用户通过手动点击「运行」按钮触发节点执行 | 测试、按需同步 |
| 定时触发 | 系统通过周期性调度触发流程执行 | 日常自动同步 |
定时触发模式配置项#
| 配置项 | 必填 | 说明 |
|---|
| 触发周期 | 是 | 可选：5分钟、10分钟、30分钟、1小时、2小时、6小时、12小时、24小时 |
固定参数配置#
| 参数名称 | 必填 | 说明 |
|---|
| 预估部门个数 | 是 | 用于列表页集成进度条的加载显示 |
| 预估用户个数 | 是 | 用于列表页集成进度条的加载显示 |
| Webhook URL | 否 | 当存在事件推送触发集成的场景时使用 |
| 连接流执行方式 | 否 | 使用Webhook触发时的执行方式：同步/异步 |
集成部门节点配置#
| 配置项 | 说明 |
|---|
| 外部部门 | 配置外部系统的部门数据来源 |
| 执行方式 | 配置节点执行方式 |
| 映射管理 | 查看和配置当前集成流属性与集成平台属性的映射关系 |
创建或更新部门节点配置#
用于在集成平台创建或更新部门信息。| 配置项 | 必填 | 说明 |
|---|
| 外部部门对象 | 是 | 指定要处理的外部部门数据对象 |
| 映射管理 | 否 | 配置上游字段与集成平台字段的映射关系 |
| 默认挂载节点 | 是 | 当上游部门未匹配到父级部门时，默认挂载至指定部门下 |
| 挂载方式 | 是 | 选择「选择节点下新建」或「选择节点下合并」 |
选择节点下新建：同步的组织架构将作为所选节点的子节点
集成用户节点配置#
| 配置项 | 说明 |
|---|
| 外部用户 | 配置外部系统的用户数据来源 |
| 执行方式 | 配置节点执行方式 |
| 账号关联设置 | 配置上游用户与集成平台用户的关联规则 |
| 映射管理 | 查看和配置当前集成流属性与集成平台属性的映射关系 |
创建或更新用户节点配置#
| 配置项 | 必填 | 说明 |
|---|
| 外部用户对象 | 是 | 指定 要处理的外部用户数据对象 |
| 映射管理 | 否 | 配置上游字段与集成平台字段的映射关系 |
| 默认挂载节点 | 是 | 当上游用户未匹配到所属部门时，默认挂载至指定部门下 |
| 挂载方式 | 是 | 选择「选择节点下新建」或「选择节点下合并」 |
完成通讯录集成节点配置#
用于完成集成流程并处理待删除用户。| 配置项 | 必填 | 说明 |
|---|
| 待删除用户阈值 | 是 | 设置删除用户的最大阈值，超出该阈值的用户将被移至待删除用户列表 |
端到端验收#
失败对象可在日志或待处理列表中定位，并能安全重试。
删除、停用和恢复分别使用测试对象验证，不从创建成功推断其行为。
风险与限制#
外部接口限流、超时、字段约束和部分成功会造成两端状态不一致。批量上线前应设置范围、停止条件和观察窗口；凭据与敏感字段只在受控配置中保存。回滚与恢复#
停止触发和调度，保留任务日志与失败对象清单，恢复上一版连接流配置后用测试对象验证。对已经写入或删除的外部数据，按目标系统备份和恢复机制处理，不能仅通过回滚连接流配置恢复。 