从钉钉同步用户数据

<PluginInfo commercial="true" name="auth-dingtalk"></PluginInfo>

介绍

钉钉插件支持将钉钉组织中的用户和部门同步到 NocoBase。除了手动执行全量同步，还可以通过 HTTP 回调或 Stream 长连接接收增量变更。

准备工作

1. 安装并启用 钉钉 和 用户数据同步 插件。
2. 在钉钉开发者后台创建企业内部应用。
3. 按照下文说明为应用开通通讯录权限并配置数据权限范围。
4. 复制应用的 Client ID 和 Client Secret。凭据配置可以参考认证：钉钉。

配置通讯录权限和数据权限范围

在钉钉开发者后台进入应用的 权限管理，开通以下通讯录权限。

权限	权限标识	是否必需	用途
通讯录部门信息读权限	qyapi_get_department_list	是	读取部门列表、部门名称和上下级关系。
通讯录部门成员读权限	qyapi_get_department_member	是	读取部门下的成员列表。
成员信息读权限	qyapi_get_member	是	读取成员详情及所属部门。
企业员工手机号信息	fieldMobile	使用手机号时必需	同步手机号；当 用户唯一标识字段 选择 mobile 时必须开通。
邮箱等个人信息	fieldEmail	否	需要同步用户邮箱时开通。

权限开通后，还需要在应用的 数据权限（部分版本显示为“通讯录权限范围”或“可见范围”）中选择允许同步的部门和员工。建议需要全量同步时选择全部员工；如果只选择部分部门或员工，NocoBase 只会同步该范围内的数据。

:::warning 接口权限决定应用可以读取哪些字段，数据权限范围决定应用可以读取哪些部门和员工，两项都需要配置。事件订阅不能代替通讯录读取权限：NocoBase 收到事件后仍会调用钉钉接口读取对应用户或部门的最新信息。 :::

如果同一个钉钉应用还用于用户登录，请另外按照认证：钉钉开通登录所需的个人信息权限；这些登录权限不属于用户数据同步的必需权限。

添加钉钉同步来源

进入 用户和权限 > 同步，点击 添加，类型选择 钉钉。

配置以下字段：

字段	说明
来源名称	当前同步来源的唯一名称。
启用	启动当前来源的事件接收，并允许执行同步任务。
Client ID	钉钉企业内部应用的 Client ID，支持使用环境变量和密钥。
Client Secret	钉钉企业内部应用的 Client Secret，支持使用环境变量和密钥。
用户唯一标识字段	可选择 mobile 或 unionId。首次同步后应保持该选项稳定；缺少所选字段的用户会被跳过。
事件接收模式	选择 HTTP 回调 或 Stream 模式，接收用户和部门的增量变更。

保存并启用来源后，先点击 同步 完成首次全量同步，再使用事件订阅处理后续增量变更。

选择事件接收模式

Stream 模式

Stream 模式由 NocoBase 服务端主动与钉钉建立持久连接，不需要公网回调地址、Token 或 EncodingAESKey。

1. 在钉钉开发者后台进入应用的事件订阅设置，选择 Stream 模式。
2. 订阅应用需要的用户和部门变更事件。
3. 在 NocoBase 中选择 Stream 模式，保存并启用同步来源。

同步来源启用后会启动 Stream 客户端。更新、停用或删除来源时，对应连接会刷新或关闭。

:::info NocoBase 服务端需要能够主动访问钉钉。Stream 模式不要求配置反向代理，也不需要提供公网入站回调地址。 :::

HTTP 回调

HTTP 回调模式通过 NocoBase 的回调地址接收钉钉事件。

1. 在 NocoBase 中选择 HTTP 回调。
2. 填写钉钉事件订阅所配置的 Token 和 EncodingAESKey。
3. 保存来源并复制生成的 事件回调 URL。
4. 将该 URL 配置到钉钉开发者后台，并订阅需要的用户和部门事件。

回调地址必须能够被钉钉访问。生产环境应通过 HTTPS 暴露该地址，并确保反向代理完整转发请求路径。

支持的增量事件

两种事件接收模式均支持以下钉钉事件：

事件	在 NocoBase 中的处理
user_add_org	创建或更新用户。
user_modify_org	更新用户。
user_leave_org	删除已同步用户。
org_dept_create	创建或更新部门。
org_dept_modify	更新部门并同步该部门的用户。
org_dept_remove	删除已同步部门。

同步字段

部门字段

钉钉字段	NocoBase 字段或用途
dept_id	部门的来源唯一标识。
name	部门名称。
parent_id	上级部门，用于建立部门层级。若上级部门不在数据权限范围内，当前部门会作为根部门同步。

用户字段

钉钉字段	NocoBase 字段或用途
mobile 或 unionid	根据 用户唯一标识字段 的配置生成用户的来源唯一标识和用户名。缺少所选字段的用户会被跳过。
name	用户昵称。
mobile	手机号。需要开通 企业员工手机号信息 权限。
email，为空时使用 org_email	邮箱。需要开通 邮箱等个人信息 权限。
dept_id_list	用户所属部门；只保留数据权限范围内的部门。
dept_order_list	主部门。
leader_in_dept	用户是否为对应部门的负责人。

部门负责人

钉钉会通过用户详情中的 leader_in_dept 标记用户在各个所属部门中是否为负责人。NocoBase 按部门分别同步该标记：同一个用户可以是多个部门的负责人，负责人部门也不一定是用户的主部门。只有数据权限范围内的部门会参与同步。

钉钉中的负责人标记被取消后，下次同步也会取消 NocoBase 中对应的负责人标记；在 NocoBase 中手动修改的负责人状态可能在下次同步时被钉钉数据覆盖。

全量同步和增量同步使用相同的字段映射。目前不会同步头像、职位、工号等其他钉钉用户字段。

故障排查

• 同步结果为空或缺少整个部门时，检查三项必需的通讯录读取权限，以及该部门是否包含在数据权限范围内。
• 用户存在但手机号或邮箱为空时，分别检查 企业员工手机号信息 或 邮箱等个人信息 权限。
• 出现“部门/员工不在权限范围内”等错误时，扩大应用的数据权限范围，而不是只重新订阅事件。
• 用户被跳过时，检查用户是否具有当前配置的唯一标识字段。
• Stream 模式可以在应用日志中搜索 Dingtalk stream client starting、Dingtalk stream client started 或连接错误。
• HTTP 回调模式需要确认回调地址可被公网访问，并检查 Token 和 EncodingAESKey 是否与钉钉配置一致。
• 修改钉钉应用权限或可见范围后，重新执行一次手动全量同步。