Skip to main content
组织管理

钉钉身份源

通过钉钉企业内部应用接入企业通讯录，配置应用凭证、权限和字段映射。

钉钉身份源用于通过钉钉企业内部应用（一方应用）将企业通讯录接入 Qoder。接入后，Qoder 可以根据配置的字段映射识别钉钉中的成员和部门信息。 本文面向负责 Qoder 身份管理和钉钉应用配置的管理员。开始配置前，请确保你同时具备 Qoder 管理权限，以及目标钉钉企业内部应用的查看和配置权限。
钉钉身份源用于同步身份目录数据，不等同于 SAML 或 OIDC 单点登录配置。

准备工作

在开始接入前，请完成以下准备：
  • 确认可以登录钉钉开发者后台，并为当前企业创建企业内部应用。
  • 确认可以查看企业 CorpId、应用 AppKey 和 AppSecret。
  • 确认可以为应用申请通讯录权限并设置权限范围。若创建应用和申请权限由不同管理员负责，请提前完成协作安排。
钉钉支持三方应用扫码授权和企业内部应用接入等方式。本文对应 Qoder 页面中的 钉钉（一方应用），需要管理员在钉钉开放平台创建企业内部应用并手动配置凭证和权限，不使用三方应用的扫码授权流程。

配置流程

钉钉开放平台和 Qoder 的配置需要交替完成：
Qoder 钉钉身份源配置路径
  1. 在钉钉开放平台创建企业内部应用，获取 CorpId、AppKey 和 AppSecret。
  2. 在 Qoder 中添加钉钉身份源，填写应用凭证并获取 Qoder 生成的回调域名。
  3. 返回钉钉开发者后台，为应用配置回调域名、申请 Qoder 所列的 6 项权限并设置权限范围。
  4. 返回 Qoder 验证权限、配置字段映射并完成接入。

在钉钉开放平台创建应用

钉钉开发者后台操作路径

创建企业内部应用

钉钉开发者后台创建应用入口
 在开发者后台首页的“应用开发指引”中点击“创建”，也可以从顶部进入“应用开发”创建企业内部应用。
  1. 登录钉钉开发者后台。
  2. 进入 应用开发 > 企业内部开发。
  3. 点击 添加应用。
  4. 按钉钉页面要求填写应用名称、应用描述、图标等基本信息，然后完成创建。
  5. 创建完成后，进入该应用的详情页。
应用名称用于钉钉开放平台内的管理和识别，可以与 Qoder 身份源的显示名称保持一致。请勿将应用创建为三方企业应用，否则无法按本文流程填写一方应用凭证。

获取企业和应用凭证

  1. 在钉钉开发者后台获取当前企业的 CorpId。
  2. 在应用详情页进入 凭证与基础信息。
  3. 复制应用的 AppKey 和 AppSecret。
  4. 将三个值保存在安全位置，稍后填写到 Qoder。
以下凭证必须来自同一个钉钉企业和同一个企业内部应用：
凭证用途获取位置
CorpId标识钉钉企业钉钉开发者后台
AppKey标识企业内部应用应用详情中的凭证与基础信息
AppSecret供 Qoder 调用钉钉接口时校验应用身份应用详情中的凭证与基础信息
AppSecret 属于敏感凭证。请勿通过聊天、邮件或工单正文发送，也不要将其写入公开文档或代码仓库。

添加钉钉身份源

  1. 进入 Qoder 组织管理后台的 设置 > 安全与身份 > 访问与身份验证。
  2. 找到 钉钉身份源，点击 添加。
  3. 继续配置应用信息。
  4. 按页面向导依次完成应用配置、权限分配和字段映射。

配置应用信息

填写以下信息：
字段是否必填说明
显示名称是身份源在 Qoder 中的名称，用于帮助管理员区分不同身份源。例如“钉钉企业通讯录”。
CorpId是当前钉钉企业的企业 ID。
AppKey是钉钉企业内部应用的应用标识。
AppSecret是与 AppKey 配对的应用密钥。输入内容默认隐藏，可按需临时显示。
页面还会生成回调域名：
地址配置要求
回调域名复制页面实际生成的值，并填写到钉钉开发者后台中该应用的回调域名配置。
请始终复制当前 Qoder 页面生成的完整地址。不要使用本文、截图或演示环境中的示例域名，也不要自行删改协议、域名、端口或路径。

在钉钉应用中配置回调域名

保持 Qoder 配置页面打开，并在钉钉应用详情中完成以下操作：
  1. 复制 Qoder 显示的 回调域名。
  2. 在钉钉应用的回调域名配置中粘贴该值。
  3. 保存钉钉应用配置。
完成钉钉侧的地址配置后，返回 Qoder，点击 下一步。如果显示名称、CorpId、AppKey 或 AppSecret 为空，页面会标记缺失字段，补充后才能继续。

分配 API 权限

钉钉身份源需要读取成员和部门信息。登录钉钉开发者后台，进入 应用开发 > 选择应用 > 权限管理，依次搜索并申请以下 6 项权限：
权限名称权限值用途
企业员工手机号信息fieldMobile读取成员手机号字段。
邮箱等个人信息fieldEmail读取成员邮箱字段。
获取通讯录基本信息qyapi_get_department_list读取部门列表等通讯录基础信息。
通讯录部门成员读权限qyapi_get_department_member读取部门与成员的归属关系。
成员信息读权限qyapi_get_member读取成员信息。
通讯录个人信息读权限Contact.User.Read读取通讯录中的个人信息。
在钉钉开发者后台中完成授权：
  1. 在应用详情页点击 权限管理。
  2. 通过权限值逐项搜索上表中的权限。
  3. 选中所需权限并提交申请。钉钉页面支持批量申请时，可以一次提交多项权限。
  4. 在 权限管理 > 数据权限 中设置应用可以访问的通讯录范围。需要同步完整企业通讯录时选择全部员工；只需同步部分成员时，选择实际需要接入 Qoder 的范围。
  5. 完成授权，并等待权限在钉钉侧生效。
权限范围决定该应用能够读取哪些成员和部门，也会限制 Qoder 可以取得的通讯录数据。后续如需调整范围，应在钉钉应用的权限或可见范围配置中修改，然后返回 Qoder 重新检测。
只申请 Qoder 页面列出的权限。不要勾选与 Qoder 接入无关的全部权限。
申请权限后，返回 Qoder 进行验证：
  • 点击某项权限后的 验证权限，可以单独检查该权限。
  • 点击 全量检查，可以一次检查全部 6 项权限。
  • 显示 未授权 时，返回钉钉开放平台检查权限是否已申请并生效，然后再次验证。
有关钉钉权限值和申请方式，请参阅钉钉开放平台权限范围说明。

配置字段映射

字段映射决定钉钉成员属性写入哪个 Qoder 身份字段。当前需要配置以下 3 个账户字段：
钉钉身份源字段映射示例
Qoder 字段属性路径钉钉字段配置说明
emailuser.emailemail（邮箱）或 org_email（企业邮箱）必须映射，用作账号关联的唯一标识。
displayNameuser.displayName按组织需要选择决定成员在 Qoder 中显示的名称。
phoneNumberuser.phoneNumbermobile（手机号）用于同步成员手机号。
email 和 org_email 都可以映射到 Qoder 的 email 字段，但数据来源不同：
  • email：钉钉成员资料中的邮箱。
  • org_email：成员在当前钉钉企业中的企业邮箱。
选择时，应以能够稳定匹配成员 Qoder 账号的邮箱为准。如果组织统一维护企业邮箱，并且目标成员的 org_email 完整有效，可以选择 org_email；否则选择 email。如果两者同时存在但值不同，应选择与成员 Qoder 账号邮箱一致的字段，避免创建重复账号或关联到错误账号。 配置映射时，请注意以下规则：
  • 邮箱映射是接入所需的账号标识映射。选择的钉钉字段必须能为需要接入 Qoder 的成员提供有效邮箱。
  • 完成接入前，建议抽查不同部门和成员类型，确认所选邮箱字段均有值。
  • 修改或移除映射会改变后续从该身份源取得的数据如何写入 Qoder。保存前请确认不会造成成员信息缺失或错误关联。
完成映射后，点击 完成接入。Qoder 将进入身份源详情页并检测应用凭证和授权状态。

检查接入状态

进入钉钉身份源详情页时，Qoder 会自动检查 AppKey、AppSecret 和已授权权限的有效状态。
  • 显示配置正常时，表示本次检查中的凭证和权限均有效。
  • 如果检测到钉钉后台的授权范围发生变化，页面会提示本地配置可能已经失效。完成钉钉侧修正后，点击 重新检测。
  • 自动提示关闭后，仍可在 授权内容 中点击 重新检测，查看每项权限的当前状态和已授权数量。
  • 可在 应用凭证 中点击 检测配对，单独检查当前 AppKey 与 AppSecret 是否匹配。
权限验证只能检查 Qoder 当前能否使用相应权限。若钉钉后台显示已申请但 Qoder 仍显示未授权，请先确认配置的是同一个企业内部应用，并确认权限已经生效。

管理钉钉身份源

接入完成后，可以在身份源详情页查看或维护应用凭证、字段映射、基本信息、回调配置和授权内容。

更新应用凭证

CorpId 在详情页中用于确认当前接入的钉钉企业。AppKey 和 AppSecret 可以分别更新。
  1. 修改 AppKey 或 AppSecret。
  2. 点击对应字段后的 保存。
  3. 在确认窗口中点击 检查保存。
  4. 等待系统校验新值与当前配对凭证是否匹配。
校验通过后，新凭证会保存并立即生效。校验失败时，本次修改不会保存；请检查 AppKey 和 AppSecret 是否来自同一个钉钉应用，然后重新检查。

更新字段映射

在字段映射中可以查看当前映射标识、已映射数量以及每个 Qoder 字段对应的钉钉字段。编辑映射后，应重新确认邮箱标识字段仍然有效，并检查 3 个账户字段是否完整。

查看回调配置

回调域名位于折叠的 回调与高级配置 区域。钉钉应用中的回调域名应与 Qoder 当前显示的值保持一致。

启用或禁用身份源

身份源详情页会显示当前连接状态，并提供启用或禁用控制。状态切换完成后，页面会更新为 已启用 或 已禁用。重新启用后，请检查凭证配对和授权状态，确认配置仍然有效。

删除身份源

点击 删除身份源 并确认后，会永久清除该身份源中的以下信息：
  • 应用凭证
  • 权限配置
  • 字段映射
  • 已同步数据
删除操作不可撤销。删除后如需恢复接入，必须重新添加并配置身份源。执行删除前，请确认不再需要该身份源及其同步数据。

常见问题

为什么无法进入下一步？

检查显示名称、CorpId、AppKey 和 AppSecret 是否均已填写。页面会标记为空的必填字段。

为什么凭证校验失败？

常见原因是 AppKey 与 AppSecret 不属于同一个钉钉企业内部应用，或者复制时遗漏了字符。请回到钉钉开放平台的同一个应用中重新获取凭证，不要在值前后添加空格。

为什么权限仍显示未授权？

请依次确认：
  1. Qoder 中配置的凭证对应当前正在授权的钉钉应用。
  2. 6 项权限均已在该应用的权限管理中申请。
  3. 钉钉侧的权限变更已经生效。
  4. 返回 Qoder 后重新执行单项验证或全量检查。

邮箱应该映射到 email 还是 org_email？

email 来自成员资料中的邮箱，org_email 来自成员在当前钉钉企业中的企业邮箱。选择能够为目标成员持续提供有效值，并且与其 Qoder 账号邮箱一致的字段。完成接入前，建议抽查不同部门和成员类型，避免部分成员缺少用于账号关联的邮箱。

修改钉钉权限后需要做什么？

返回身份源详情页，在 授权内容 中点击 重新检测。如果页面提示配置发生变化，应在钉钉侧修正权限后再次检测，直到所需权限全部显示为已授权。