跳到主要内容

单点登录

团队空间的所有者和管理员可为当前团队空间配置企业单点登录（SSO）。配置完成后，成员可通过钉钉扫码登录并加入该团队空间。

启用钉钉 SSO 后，通过团队邀请链接加入的受邀者须使用该企业的钉钉登录，不再提供手机号验证码登录入口。

同一企业内部应用也可用于向成员发送 钉钉工作通知（见 通知配置）。工作通知与扫码登录共用 CorpId / AppKey / AppSecret，但需要额外权限与 AgentId。

同一企业内部应用还可以开启 钉钉群机器人，让成员在群里通过 @机器人 创建 AntTodo 任务。群机器人不需要 AgentId，但必须复用当前 SSO 应用并完成机器人能力、HTTP 回调和应用发布配置。在 设置 → 团队配置 → 快速创建 中接入。详见连接器。

钉钉登录​

在 AntTodo 中使用钉钉企业内部应用登录前，请先在钉钉开放平台创建并配置企业内部应用，再将凭证填写到团队空间的「设置 → 单点登录」。

1. 获取 CorpId​

  1. 使用企业管理员账号登录 钉钉开放平台。
  2. 进入开发者后台后，在首页查看当前企业的 CorpId（企业标识）。

CorpId 是企业在钉钉中的唯一标识，通常形如 dingxxxxxxxxxx。

2. 获取 AppKey、AppSecret 与 AgentId​

  1. 在钉钉开放平台进入目标企业内部应用的应用详情。
  2. 打开 基础信息 → 凭证与基础信息。
  3. 复制 AppKey（Client ID）与 AppSecret。
  4. 若需发送钉钉工作通知，一并复制 AgentId（应用 AgentId）。

AppSecret 仅在配置时写入 AntTodo，不会在界面上回显明文。仅做扫码登录时 AgentId 可留空；开启钉钉通知渠道时必须填写。

3. 配置重定向 URL​

  1. 在应用详情中打开 开发配置 → 安全设置。
  2. 将重定向 URL / 回调地址配置为：
https://app.anttodo.com/auth/dingtalk/callback

请使用与线上应用一致的地址；本地调试时需按实际公网回调域名另行配置。

4. 申请权限​

在应用详情中打开 权限管理，按能力开通下列权限。控制台文案可能随钉钉版本略有差异，请以实际选项为准。

扫码登录（必选）​

权限用途
Contact.User.mobile读取用户手机号，用于匹配或创建 AntTodo 账号
Contact.User.Read读取用户基本信息（含 unionId 等）

未开通上述权限时，扫码可能成功，但无法完成用户信息换取与账号关联。

钉钉工作通知（可选，发通知时必选）​

AntTodo 发送工作通知时会调用：

  • gettoken：获取应用 access_token（使用 AppKey / AppSecret）
  • topapi/user/getbyunionid：将登录身份中的 unionId 解析为企业 userid
  • topapi/message/corpconversation/asyncsend_v2：向指定员工发送工作通知

扫码登录成功后，AntTodo 还会用同一套应用凭证调用 getbyunionid，把解析到的 userid 写入账号绑定，供后续发工作通知使用。因此下列通讯录权限不仅发通知时需要，首次建立钉钉身份绑定时也必须开通。

请在权限管理中申请并开通下列权限（控制台名称可能略有差异，请以权限点为准）：

权限点 / 常见名称用途
qyapi_get_member（通讯录成员读权限 / 根据 unionId 获取用户 userid）调用 getbyunionid；未开通时钉钉常返回 60011，扫码仍可登录，但无法写入 userid，钉钉通知也发不出去
企业内机器人发送消息 / 工作通知 / 发送工作通知调用 asyncsend_v2 投递工作通知

未开通 qyapi_get_member 时，成员侧表现通常是：钉钉扫码登录成功，但后台始终没有企业 userid，到期提醒等钉钉渠道通知不会送达。

同时请确认：

  1. AntTodo「单点登录」中已填写 AgentId。
  2. 应用的 可见范围 覆盖需要接收通知的企业成员。
  3. 权限变更后已重新 发布应用版本；仅开通权限未发布时，成员侧通常仍不可用。
  4. 开通并发布后，请让成员重新钉钉扫码登录一次，以便补写 userid。

缺少 AgentId、qyapi_get_member 或工作通知发送权限时，成员仍可正常扫码登录，但无法收到钉钉渠道通知；产品内「系统通知」不受影响。

5. 发布应用​

  1. 在钉钉开发者后台完成上述配置后，进入应用的 版本管理与发布（或「发布」相关入口）。
  2. 创建并提交应用版本，将应用发布到企业内可用状态。

仅完成开发配置而未发布时，企业成员通常无法正常使用该应用完成扫码登录或接收工作通知。

在 AntTodo 中完成配置​

取得上述信息并完成权限申请与应用发布后：

  1. 以所有者或管理员身份打开对应团队空间。
  2. 进入 设置 → 单点登录，选择「钉钉企业登录」并填写：
    • CorpId
    • AppKey
    • AppSecret
    • AgentId（发送钉钉工作通知时必填；仅登录可留空）
  3. 保存时请确保 AppKey 与 AppSecret 来自同一应用。更换 AppKey 后必须重新填写 AppSecret；仅改 AppKey 会导致扫码成功但回调换票失败。
  4. 需要钉钉通知时，成员在 设置 → 通知配置 中按场景开关「钉钉通知」（仅在已配置钉钉 SSO 时显示该列）。详见 通知配置。
  5. 保存后，将团队域名分享给成员。成员访问 {团队Slug}.team.anttodo.com 时，仅可使用钉钉扫码登录；主站 app.anttodo.com 仅提供手机号登录。

团队登录域名​

每个团队空间拥有唯一 Slug，并对应三级域名：

https://{团队Slug}.team.anttodo.com/

例如 Slug 为 yucekj 时，登录入口为 https://yucekj.team.anttodo.com/。

钉钉 OAuth 回调仍固定为：

https://app.anttodo.com/auth/dingtalk/callback

桌面端与手机端（iOS）在授权完成后，会通过一次性 handoff 码经 anttodo://auth/callback 回到客户端继续会话；浏览器 Web 端则在回调页直接建立登录会话。

可在「设置 → 团队管理」查看域名，或在「设置 → 单点登录」复制团队登录域名。