跳到主要内容

钉钉

钉钉集成用于把卷王接入企业钉钉身份体系，支持钉钉账号登录、账号绑定，以及从钉钉同步部门和成员。

使用场景​

  • 企业成员通过钉钉账号快捷登录卷王
  • 已有卷王账号绑定钉钉账号
  • 将钉钉通讯录中的部门和成员同步到卷王
  • 让内部问卷、考试、审批类场景使用统一的企业成员身份

配置前准备​

  • 具有钉钉组织管理员或应用开发权限
  • 卷王已部署到用户浏览器可访问的地址
  • 已确认卷王登录页地址，例如 https://你的系统域名/user/login
  • 已准备卷王管理员账号，用于填写配置和执行同步任务

操作步骤​

1. 在钉钉控制台创建自建应用​

访问 钉钉管理后台，使用有权限的管理员账号登录。

钉钉应用列表

创建企业内部自建应用，按实际业务填写应用名称、描述和图标。

创建钉钉自建应用

创建完成后，点击 设置，再点击 去开发。

进入钉钉应用开发

进入应用详情后，打开 基础信息 -> 凭证与基础信息，记录以下信息：

  • Client ID
  • Client Secret

部分钉钉页面也会把这两个字段称为 AppKey 和 AppSecret。后续在卷王后台填写时，对应填入 Client ID 和 Client Secret。

查看钉钉应用凭证

2. 配置重定向 URL​

在钉钉应用左侧进入 安全设置，配置重定向 URL。

常见回调地址包括：

  • 登录页：https://你的系统域名/user/login
  • PC 端账号绑定页：https://你的系统域名/user/binding

如果系统部署在非标准端口、二级路径或内网域名下，需要填写用户浏览器实际访问到的完整地址。协议、域名、端口和路径要与实际地址一致。

配置钉钉重定向 URL

3. 添加应用权限​

进入 权限管理，为自建应用添加登录和通讯录同步需要的权限。

建议至少添加以下权限：

  • Contact.User.Read
  • qyapi_get_department_list
  • qyapi_get_member
  • qyapi_get_department_member
  • open_app_api_base
  • qyapi_base

如果只接入钉钉登录，不同步组织架构，可以先保留登录相关权限；如果需要同步部门和成员，必须确保通讯录相关权限已经授权。

配置钉钉应用权限

4. 发布应用版本​

所有配置完成后，进入应用发布页面，创建并发布一个版本。

发布钉钉应用版本

确认版本信息后提交发布。

提交钉钉应用发布

5. 在卷王后台填写钉钉登录配置​

登录卷王后台，进入 基础设施 -> 配置管理，找到 钉钉登录 配置。

点击编辑后填写：

  • 开启状态：开启
  • Client ID：钉钉应用的 Client ID
  • Client Secret：钉钉应用的 Client Secret

保存后，PC 端登录页会显示钉钉登录入口。

卷王后台配置钉钉登录

6. 同步钉钉部门和成员​

如果需要把钉钉通讯录同步到卷王，进入 基础设施 -> 定时任务，新建钉钉同步任务。

推荐配置：

  • 任务名称：钉钉同步
  • 处理器的名字：dingtalkSyncJob
  • 处理器的参数：首次同步可留空
  • CRON 表达式：例如 0 0 2 * * ?，表示每天凌晨 2 点执行

处理器参数可按需要填写：

  • 留空：同步部门和成员
  • dept：只同步部门
  • user：只同步成员
  • dept,user：同步部门和成员

首次配置完成后，建议先点击 执行一次，确认部门、成员和钉钉账号绑定关系都能正常生成。

创建钉钉同步任务

验证方式​

完成配置后，可以按以下顺序验证：

  1. 打开 PC 端登录页，确认 其他登录方式 中出现钉钉图标。
  2. 点击钉钉登录，确认可以跳转到钉钉授权页。
  3. 使用已同步或已绑定的钉钉账号授权登录。
  4. 在后台用户管理中检查用户、手机号、邮箱、部门和账号绑定关系是否同步正确。

如果用户尚未同步或尚未绑定钉钉账号，钉钉授权成功后可能会提示第三方账号未绑定。此时可以先执行一次钉钉同步，或让用户使用账号密码登录后，在个人设置中绑定钉钉账号。

常见问题​

登录页没有钉钉入口怎么办？

先检查卷王后台 钉钉登录 是否已开启，并确认 Client ID 和 Client Secret 已保存。钉钉登录入口当前主要显示在 PC 端登录页，移动端页面可能不会展示该入口。

点击登录后提示重定向地址不合法怎么办？

检查钉钉应用 安全设置 中的重定向 URL。需要把用户浏览器实际访问的登录页或绑定页地址加入白名单，尤其注意 http / https、域名、端口和二级路径是否一致。

同步任务执行失败，提示 ClientId 或 ClientSecret 未配置怎么办？

说明卷王后台没有读取到钉钉应用凭证。回到 基础设施 -> 配置管理 -> 钉钉登录，重新填写并保存 Client ID 和 Client Secret。

同步后没有部门或成员怎么办？

检查钉钉应用是否已经发布，通讯录相关权限是否已经添加并授权。确认无误后，在卷王定时任务中重新执行一次 dingtalkSyncJob。

只使用钉钉登录，不同步通讯录可以吗？

可以。钉钉登录和通讯录同步不是强绑定关系。只接入登录时，需要用户先在个人设置中绑定钉钉账号；如果希望新员工自动创建账号并绑定钉钉身份，再配置同步任务。