钉钉数据同步集成

最后更新：2022-09-16

所有数据同步集成方案的实现使用IDP中的Connector组件来完成。
此处的数据指：组织机构数据，账户数据与组数据（组数据可选，没有不影响同步功能）。

1. IDP同步数据到钉钉

1.1. 场景描述

image.png
应用场景图描述：
（1） 管理员在IDP4统一身份认证平台设置SCIM同步任务，同步任务可设置实时同步、手动同步、定时同步；
（2） IDP4统一身份认证平台触发同步任务后通过SCIM接口将用户信息同步到IDsConnector系统；
（3） IDsConnector系统当收到IDP统一身份认证平台同步的数据时会提供标准协议或API接口的方式同步到钉钉中。

1.2. 支持的对象

支持同步组织机构、用户。

1.3. 同步模式

使用connector配置IDP4到钉钉的同步，同步计划配置为：
image.png

  • 数据接收方式：主动拉取；

  • 数去拉取模式: 分页拉取模式;

1.4. IDsConnector配置方式

1.4.1. 创建应用

要实现数据推送，创建一个应用是必不可少的，我们会创建同步任务时选择使用的应用。
登录管理员>添加应用>选择jwt模板(或者直接使用已经创建的其他应用)
并开启应用的API
image.png image.png

1.4.2. 应用授权

创建好应用后，在应用详情中的数据范围设置该应用允许的数据范围和接口范围 比如下图中,分别授权的所有人事组织节点的权限 和账户组织机构的获取接口权限

image.png

image.png

1.4.3. 新建同步目标

  1. 在connector的目标管理页面，点击新建同步目标

    image.png

  2. 配置同步目标


    目标管理配置如图：
    image.png

    • 目标名称：随意填写，注意唯一性即可；

    需要注意的是来源和来源的环境必须是一样的，否则不会执行同步任务
    image.png

    • 目标主类型：其他应用协议类型(APP_STANDARD)

    • 目标子类型：钉钉V2版本(DINGDING_TALK_V2_SCHEMA)

    • 钉钉oapi地址：固定值，https://oapi.dingtalk.com

    • cropId：钉钉组织ID，获取方式看下面的截图

    image.png

    • 应用appKey：钉钉微应用的appKey，获取方式看下面的截图

    • 应用appSecret：钉钉微应用的appSecret，获取方式看下面的截图

    image.png

    • 钉钉根组织ID：钉钉中默认根组织id（在钉钉目标中，该配置项并没有作用，后续会去掉）

    • 专属帐号推送模式：是否推送专属账户,打开后不能指定loginEmail或mobile

    • 专属帐号类型：打开专属账户才有效,默认企业自建账户,

    • 部门扩展属性：钉钉中部门的扩展属性（预留字段，可以不填写）

    • 用户扩展属性：钉钉中账户的扩展属性 （钉钉中支持未用户增加扩展字段，需要把钉钉中定义的扩展字段，填写到这里，多个扩展字段用英文半角逗号分隔开；这里配置好后，在映射模板配置环节，就可以基于这些扩展字段，进行自定义映射）

    • 创建默认群组：开启后，创建部门时会创建默认的群组

    • 部门通讯录可见性：开启后，部门下的员工只能看到所在部门及下级部门通讯录

    • 限制本部门成员查看通讯录：开启后，部门下的员工只能指定范围的通讯录

    • 是否默认同意加入该部门的申请：是否默认同意加入该部门的申请：开启后:表示加入该部门的申请将默认同意。关闭:表示加入该部门的申请需要有权限的管理员同意

    • 自动匹配同名部门：新增部门时，如果部门在同一父级下已经存在同名部门，可以直接匹配部门。

    • 用户所属部门字段非法处理策略（新增时）: 新增用户时，如果用户的父级组织机构ID字段不合法时，可以选择直接添加到默认根节点，或者报错

    • 用户所属部门不存在时处理策略（新增时）: 新增用户时，如果用户的父级组织机构ID字段不存在时，可以选择直接添加到默认根节点，或者报错

    • 用户所属部门字段非法处理策略（更新时）: 更新用户时，如果用户的父级组织机构ID字段不合法时，可以选择保存不变，或者报错

    • 用户所属部门不存在时处理策略（更新时）: 更新用户时，如果用户的父级组织机构ID字段不存在时，可以选择保存不变，或者报错

  3. 点击“测试连接”，确保连接的参数配置正确，如果测试连接成功，点击“保存”

    注意：

    • 钉钉的接口可以设置IP白名单，请确认IDsConnector的公网出口IP在钉钉的白名单范围内，否则会导致接口调用失败

    image.png

    • 确保钉钉填写的钉钉密钥具有通讯录的访问权限，如下图：

    image.png​

1.4.4. 配置映射模板

IDP4同步数据到钉钉的默认模板如下（早期版本没有默认模板，可以参考下图手动添加）：
image.png

1.4.5. 保存同步任务

机构及组的组织树中，选中“人事组织”或其下的任意节点后，在“导出”里点击“添加推送任务”，进行推送任务的表单填写，我们先创建一个全量推送任务，这里就不开启增量,保存后即可完成同步任务的创建。
image.png
image.png

1.5. 注意事项

1.5.1. 专属钉推送

只需要同步目标里面打开专属账号推送模式即可,具体看4.2
image.png
注意:专属账号推送时,不会推送loginEmail和mobile

2. 钉钉同步数据到IDP

2.1. 场景描述

image.png
应用场景图描述：
（1） 管理员在IDsConnector系统中创建同步任务，同步任务的触发可设置为手动或自动两种方式；
（2） 触发同步任务后IDsConnector系统通过调用接口拉取钉钉组织的部门和账户数据；
（3） IDsConnector系统会将拉取到的部门/用户数据通过SCIM的方式推送IDP4系统中

2.2. 支持的对象

支持同步组织机构、用户。

2.3. Connector配置方式

image.png
说明配置流程如上。如果没有特殊需求，可以跳过创建映射模板操作，直接使用connector内置的映射模板，或者再创建同步任务中进行调整。

2.3.1. 创建应用

要实现数据推送，创建一个应用是必不可少的，我们会创建同步任务时选择使用的应用。
登录管理员>添加应用>选择jwt模板(或者直接使用已经创建的其他应用)
并开启应用的API
image.png image.png

2.3.2. 应用授权

创建好应用后，在应用详情中的数据范围设置该应用允许的数据范围和接口范围 比如下图中,分别授权的所有人事组织节点的权限 和账户组织机构的获取接口权限

image.png

image.png

2.3.3. 新建同步来源

  1. 登录 connector 之后，在来源管理页面点击新建同步来源

    image.png

  2. 配置同步来源
    来源管理配置如图：

    image.png

    • 来源名称：随意填写，注意唯一性即可；

    下面还有一个环境的选择，默认是开发环境。需要注意的是来源和目标的环境必须是一样的，否则不会执行同步任务
    image.png

    • 来源主类型：APP_STANDARD

    • 来源子类型：选择DINGDING_TALK

    • 钉钉oapi地址：固定值，https://oapi.dingtalk.com

    • cropId：钉钉组织ID，获取方式看下面的截图

    image.png

    • 应用agentId：钉钉微应用的ID，获取方式看下面的截图

    • 应用appKey：钉钉微应用的appKey，获取方式看下面的截图

    • 应用appSecret：钉钉微应用的appSecret，获取方式看下面的截图

    image.png

    • 钉钉根组织ID：拉取的钉钉“根节点”ID。如果是钉钉的根组织机构，则直接填1。否则需要查询部门的ID

    image.png

    • IDaaS租户ID：IDP租户的租户ID

    • 关联同步任务ID：创建同步任务后再配置改参数值，用于注册钉钉回调事件

    • IDaaS根组织ID：要同步到IDP的组织的外部ID

    image.png

    • IDsConnector后端地址：connector的后端地址，用于注册钉钉回调事件

  3. 点击测试连接，确保连接的参数配置正确。然后点击保存

2.3.4. 映射模板

connector 中内置了一部分常用的映射模板，如果没有特殊需求的话可以直接使用。
image.png
映射属性对应如图，左侧是钉钉的字段名，右侧是IDP中的字段名
image.png
注意：此处的机构的所属父部门ID的映射字段有误，旧的已建的需要删除掉，添加新的parentExternalId

在connector4.11的版本，映射模板中已经修改，可直接添加

2.3.5. 新建同步任务

在IDaaS中，机构及组的组织树中，选中“人事组织”或其下的任意节点后，在“导入”里点击“添加拉取任务”，进行拉取任务的表单填写
image.png
image.png

  • 任务名称：按需填写任务名称。

  • 数据拉取来源：下拉展示可选择的来源，下拉列表从connector中获取。选择刚刚创建的钉钉来源。

  • 映射模板：下拉展示可选择的映射模板，下拉列表从connector中获取。选择刚刚创建的映射模板或者直接使用默认的IDP4-钉钉V2(默认)。

  • 来源根节点标识：不必填，不填时为空。对应connector同步任务创建时的“来源根节点标识”一项。

  • 目标根节点标识：不必填，不填时默认使用IDaaS人事组织根节点的外部id：main。对应connector同步任务创建时的“目标根节点标识”一项。

  • 关联应用：选取相关的应用。此选择，会影响同步时用户在应用群组内子账户和应用群组内数据字典的同步值。

2.3.6. 导入扩展字段

扩展字段钉钉钉同步.xls
下载附件并导入到 IDP 的数据字典中，附件是connector同步时需要的扩展字段
image.png

配置完成后，点击立即同步就可以将钉钉的数据拉取到IDP指定的机构中。