钉钉数据同步集成

最后更新：2021-12-06

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

IDP同步数据到钉钉

一、场景描述

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

二、支持的对象

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

三、同步模式

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

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

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

四、IDsConnector配置方式

image.png
说明配置流程如上。由于IDP4到钉钉目前没有现成的映射模板，需要手动在映射模板中进行创建或者在创建同步任务中进行创建。

4.1 新建同步来源

此步骤非必须，默认会初始化IDP4来源

  1. 先登录IDP，创建一个应用，并开启应用的APIimage.png

  2. 登录IDsConnector，在来源管理页面，点击“新建同步来源”

    image.png

  3. 配置同步来源参数，来源管理配置如图：

    image.png

    • 来源名称：随意填写，注意唯一性即可；还是需要注意一下选择的环境是否和目标管理的一致

    image.png

    • 来源主类型：SCIM

    • 来源子类型：IDP4_SCIM

    • Basic URL：IDP4的域名或者IP，如果有负载要填写负载的地址，如 http://{IDaaS_server}

    • Client ID ： IDP4中创建的应用的 API Key

    • Client Secret：IDP4中创建的应用的 API Secret

    • 版本号：固定为 v1.2 （该字段是预留的，以应对后续IDP的API做了版本升级时，进行兼容处理，当前固定值 v1.2）

  4. 点击“测试连接”，确保连接的参数配置正确，如果测试通过，点击“提交”

4.2 新建同步目标

  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​

4.3 配置映射模板

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

4.4 在IDsConnector创建密钥

如有已有密钥,可以直接跳过该步骤

IDP4在向外推送数据时，需要在应用位置配置SCIM【即下文中的4.6步骤】，配置SCIM时，需要一个Oauth认证的AK和SK. 改AK\SK可以在IDsConnector的“密钥管理”生成；
image.png        如上图，点击“新建密钥”后，打开如下界面，需要输入密钥名称，密钥名称需要唯一；描述信息可以为空，或者输入该密钥的用途等。
image.png
点击“保存”，密钥创建成功默认是禁用状态，需要在列表页点击“启用”。
image.png

4.5 保存同步任务

  1. 在同步任务中点击“新建同步任务”

    image.png

  2. 在“同步来源”页签中选择之前创建的IDP4来源

    image.png

    • 来源根节点标识：填写IDP4的根节点的外部ID，可以在IDP4中点击“根节点–详情”进行查看。

    • 同步范围：可以选择同步账户或者机构

  3. 在“同步目标”页签中选择之前创建的 钉钉 目标

    image.png

    • 目标根节点标识：如果指定钉钉根组织为根节点，填 1 。如果不是根组织，则需要填写部门的部门ID。获取方式如下：

    image.png

    • 默认密码：可以不用填

    • 检测模式：开启之后，新增账户时会先向钉钉查询该账户是否在钉钉中已存在，如果存在的话就会做修改操作。

  4. 在“属性映射”页签中。如果之前创建过映射模板，可以直接点击导入映射模板。否则需要手动创建

    image.png
    映射规则如下，可以满足基本的UD操作的同步
    image.png

  5. 配置同步计划，根据上面同步模式的介绍进行配置即可。

  6. 在“SCIM配置”页签中,选择刚刚创建的密钥

    image.png

五、注意事项

5.1 专属钉推送

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

钉钉同步数据到IDP

一、场景描述

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

二、支持的对象

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

四、Connector配置方式

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

4.1 新建同步来源

  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. 点击测试连接，确保连接的参数配置正确。然后点击保存

4.2 新建同步目标

此步骤非必须，默认会初始化IDP4目标

  1. 先登录IDP，创建一个应用，并开启应用的API

    image.png

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

    image.png

  3. 配置同步目标参数

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

    • 目标名称：随意填写，注意唯一性即可；还是需要注意一下选择的环境是否和来源管理的一致

    image.png

    • 目标主类型：选择SCIM

    • 目标子类型：IDP4_SCIM

    • Basic URL：IDP 的域名或者IP，如 https://iroiuldfai.login.aliyunidaas.com

    • Client ID ：IDP中创建的应用的API Key

    • Client Secret：IDP中创建的应用的API Secret

    • 版本号：固定为 v1.2（注意v需要小写！！）

  4. 点击测试连接，确保连接的参数配置正确。然后点击提交

4.3 映射模板

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

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

4.4 新建同步任务

  1. 在同步任务中点击新建同步任务

    image.png

  2. 在“同步来源”页签中选择之前创建的钉钉来源

    image.png

    • 来源根节点标识：在拉取钉钉/IDP数据时，可以用一个唯一标识来指定拉取的范围。需要和钉钉来源配置的 钉钉根组织ID 一致。

    • 同步范围：可以选择同步账户或者机构

  3. 在“同步目标”页签中选择之前创建的 IDP目标

image.png

  • 目标根节点标识：要同步到IDP的组织外部ID，需要和钉钉来源配置的 IDaaS根组织ID 一致。

  • 默认密码：钉钉账户到IDP时，IDP默认的登录的密码

  • 检测模式：开启之后，新增账户时会先向IDP查询该账户是否在IDP中已存在，如果存在的话就会做修改操作。

  1. 在“属性映射”页签中，点击导入映射模板

    image.png这里会根据前两步选择的来源和目标，自动过滤符合条件的映射模板，点击确认导入。
    image.png

    这里展示的就是这个同步任务具体用到的字段映射规则，可以根据需求进行调整。
    image.png
    注意：此处的机构的所属父部门ID的映射字段有误，旧的已建的需要删除掉，添加新的parentExternalId

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

  2. 配置同步计划

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

    • 同步模式为：主动拉取

    • 同步模型为：分页拉取模式；（选错了无法拉取钉钉账户）

    其他参数配置如定时同步、多线程等可以根据下列说明选择开启或关闭。

    • 数据接收方式

      • 主动拉取：来源如果提供接口，可以让connector主动调用接口来拉取数据，则选择主动拉取模式。

      • 被动接收：来源如果没有提供接口可以让connector调用拉取数据，但是有向connector推送数据的能力的话，可以选择被动接收模式。

    比如IDP推送账户到RAM的时候，因为IDP没有提供拉取数据的接口。同步这个操作是从IDP发起的，所以在connector配置的时候就需要选择被动接收模式。
    也因为 connector 只能等 IDP 主动推送数据，所以同步计划这边的其他配置项就没有意义了，选在被动接收的时候其他的配置项会在前端进行隐藏。
    image.png

    • 数据拉取模式

      • 活动目录模式：在拉取AD数据的时候，是逐层递归拉取的。不需要考虑子级机构的问题，直接将拉取到的机构和账户推送到下游。

      • 经典模式：全量拉取到机构后，在connector中重新组成有序的机构树，然后再向下游推送数据。确保不会因为父级组织机构没有推送导致子级组织机构推送失败。

    • 线程模式

      • 独享线程池：独占一定的线程数，使用这些线程并发进行同步

      • 共享线程池：与其他同步任务共享所有的线程

      • 不适用线程池：数据一个一个推送，不会出现父级机构不存在导致的失败，但比较慢

    • 仅同步用户使用线程池：使用线程池之后会出现该选项。

    开启后，会一个一个推送机构，机构推送完成之后。再使用线程池进行账户的推送。机构全部推完之后，账户与账户之间是没有层级关系的，所以可以使用线程池并发推送账户，提高数据同步的效率

    • 是否允许并发调度：开启之后允许多线程并发执行同步

    • 是否开启定时同步：配置完成后可以周期或在设定的时间点执行同步任务。不需要手动执行

4.5 导入扩展字段

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

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