钉钉集成
巴克励步
概述
Baklib 支持通过 钉钉 OAuth2 实现：成员使用钉钉扫码/授权登录组织、在钉钉工作台打开 Baklib、以及（配合同步能力）对接组织架构。配置在 组织管理后台 → 第三方集成 完成，与单个应用设置无关。
本篇说明集成市场入口、钉钉 OAuth2 安装表单填写要点，以及成员侧绑定与登录。企业微信见 企业微信集成。
操作步骤
步骤一：进入第三方集成
- 在工作台点击 组织管理 → 管理后台（或直接进入
/admin）。 - 左侧 管理 分组中选择 第三方集成。
- 若尚未安装任何集成，页面提示 还没有安装任何第三方集成，马上去添加。
预期结果：看到已安装集成列表（可为空）及 添加集成 按钮。
步骤二：安装钉钉 OAuth2
- 点击 添加集成，进入集成市场（
/admin/integrations/choose）。 - 在列表中找到 钉钉 OAuth2（类型 oauth2，说明：让用户可以通过钉钉账号登录）。
- 悬停卡片点击 安装，或进入详情页。
- 在安装表单中填写从钉钉开放平台获取的参数：
| 字段 | 说明 |
|---|---|
| Client ID | 钉钉应用 AppKey |
| Client Secret | 钉钉应用 AppSecret |
| CorpId | 钉钉组织 ID，在钉钉后台「企业信息」查看 |
| 事件回调 AESKey / Token | 若启用事件订阅，按钉钉文档填写（43 位 AESKey 等） |
| 备注 | 便于后台识别，选填 |
- 页面会显示 OAuth 回调域名 示例：
https://baklib.com。 - 将回调地址配置到钉钉开放平台「接入登录」的重定向 URL 中并保存。
- 提交 Baklib 表单，完成安装。
注意：钉钉后台的回调域、IP 白名单、权限开通须与 Baklib 页面提示一致；配置错误会导致扫码登录失败。
预期结果：第三方集成列表出现「钉钉 OAuth2」；组织登录页显示 通过钉钉登录。
步骤三：成员绑定钉钉账号
组织成员若需用钉钉身份访问 Baklib：
- 成员进入 个人中心 → 账号绑定。
- 绑定个人钉钉账号。
- 下次在组织登录页选择 通过钉钉登录，按提示授权 同意。
预期结果：授权成功后进入该成员在组织内的 Baklib 账号。
步骤四：开通钉钉开放平台权限
OAuth2 安装完成后，须在钉钉开放平台为对应应用开通读取权限，否则扫码登录或同步可能失败：
- 登录 钉钉开放平台 → 应用开发 → 进入已创建的应用详情。
- 打开 权限管理，按 Baklib 安装页提示开通用户身份、通讯录读取等权限（如
Contact.User.Read、部门列表、成员读取等）。 - 在 安全设置 中配置 重定向 URL（回调域名），与 Baklib 表单显示的
https://{组织域名}/-/oauth/dingtalk/callback一致。 - 若启用事件订阅，在 事件订阅 中填写 Baklib 提供的 SyncHTTP 推送地址与 AESKey/Token（与 OAuth 回调地址不同）。
预期结果：权限项显示已开通；回调域与安全设置与 Baklib 侧一致。
步骤五：钉钉工作台添加网页应用
让成员从钉钉工作台直接进入 Baklib 后台或站点（免登入口）：
- 在钉钉开放平台创建或选择 企业内部应用，添加 网页应用 能力。
- 配置网页应用地址：
- 打开组织后台：
https://{组织域名}/-/third_party/dingtalk/entry - 打开指定站点：
https://{组织域名}/-/third_party/dingtalk/entry?back_to={站点前台URL}
- 打开组织后台：
- 在 Baklib 组织管理后台 → 第三方集成 中录入钉钉应用的 AppKey、AppSecret、CorpId 等（与步骤二表单一致）。
- 按钉钉文档开启用户身份、通讯录、部门与成员读取等权限；建议配置 事件订阅 以自动同步组织架构变更（部门变更、员工增删）。
- 发布应用并在工作台验证能否打开 Baklib 页面。
提示：实施前确认钉钉侧管理员权限、应用可见范围，以及 Baklib 组织与钉钉企业的一对一对应关系。数据模型与部门树说明见 组织用户与组织架构。
预期结果：成员在钉钉工作台点击应用图标可进入 Baklib 后台或指定站点。
步骤六：同步组织架构与员工
在已安装钉钉 OAuth2 的前提下，可将钉钉部门与员工同步到 Baklib 组织（60 章写对接操作，组织章写数据模型）：
同步部门
- 组织管理员进入 组织管理后台 → 部门/员工管理。
- 点击 同步部门，选择钉钉来源并执行同步。
- 同步成功的部门名称左侧图标显示为主题色；未同步部门为灰色。
注意：部门同步仅同步部门名称与上下级关系，不会自动导入部门内员工。员工须在个人中心绑定钉钉后，通过钉钉扫码登录才会归入对应部门。
同步员工
- 在 部门/员工 中点击 新增员工 → 与企业微信/钉钉同步数据。
- 选择同步范围并完成字段映射。
- 确认导入方式：
- 增量导入：已存在员工更新信息，不重复创建。
- 完全同步：未出现在导入清单中的员工将被删除，请谨慎使用。
应用访问授权：在应用 访问控制 中选择 组织部门授权 时，指定同步部门成员可通过钉钉扫码登录后访问页面，详见 访问控制与授权。
预期结果：部门树与钉钉一致；绑定钉钉的成员登录后出现在对应部门。
步骤七：钉钉群内快捷入口
在钉钉群配置 酷应用 / 群快捷入口，让成员在群聊内一键打开 Baklib 页面：
- 在钉钉开放平台对应应用中，添加 酷应用 能力，选择 扩展到群会话。
- 填写快捷入口名称、图标与 快捷应用地址：
- 方式 A（直链）：
https://{站点域名}/path/to/page - 方式 B（与工作台一致）：
https://{组织域名}/-/third_party/dingtalk/entry?back_to=https://{站点域名}/
- 方式 A（直链）：
- 在钉钉 HTTP 安全域名 中放行 Baklib/站点域名。
- 发布后在目标群验证：点击入口 → 钉钉内置浏览器打开 Baklib 页面。
快捷入口只负责打开哪个 URL；页面是否可访问仍受 Baklib 站点访问控制 与登录态约束。
预期结果：群内显示快捷按钮，点击可打开已发布的 Baklib 站点或文章页。
常见问题
Q：回调域名填什么？
A：以安装表单显示的
A：以安装表单显示的
https://{host}/-/oauth/dingtalk/callback 为准，勿遗漏路径。Q：安装后登录页没有钉钉入口？
A：确认集成状态为已启用；成员是否访问正确的组织域名登录页。
A：确认集成状态为已启用；成员是否访问正确的组织域名登录页。
Q：钉钉集成与应用 SSO 有何区别？
A：钉钉 OAuth2 是组织级第三方登录；应用 访问控制 中的企业 SSO 针对单个站点访客，见 访问控制与授权。
A：钉钉 OAuth2 是组织级第三方登录；应用 访问控制 中的企业 SSO 针对单个站点访客，见 访问控制与授权。
Q：事件回调地址是什么？
A：表单中的 SyncHTTP 推送地址（如
A：表单中的 SyncHTTP 推送地址（如
/-/third_party/dingtalk/callback）用于钉钉事件订阅，与 OAuth 回调不同。相关阅读
- 企业微信集成
- 访问控制与授权 — 站点级 SSO
- 成员和用户有什么区别？
- 旧站：钉钉 OAuth2 配置