web 系统对接钉钉三方登录完整步骤实战使用示例

Web 系统对接钉钉三方登录完整步骤实战

以下是基于 OAuth 2.0 授权码模式 的完整对接流程（以扫码登录为例）：

---

一、准备工作

1. 注册钉钉开发者账号
   钉钉开放平台 → 创建企业内部应用（或第三方应用）

   • 记录 AppKey 和 AppSecret
   • 配置 回调域名（如 https://yourdomain.com/callback）

2. 授权权限
   在应用权限中开启 成员信息读权限（auth/user）

---

二、前端实现：生成登录二维码

<script src="https://g.alicdn.com/dingding/dinglogin/0.0.5/ddLogin.js">script>

<div id="dingtalk-login-container">div>

<script>
  window.DDLogin({
    id: "dingtalk-login-container",  // 容器ID
    goto: encodeURIComponent("https://oapi.dingtalk.com/connect/qrconnect?appid=APP_KEY&response_type=code&scope=snsapi_login&state=YOUR_STATE&redirect_uri=REDIRECT_URI"),
    width: 365,
    height: 400
  });
script>

参数说明：

• APP_KEY: 钉钉应用的AppKey
• REDIRECT_URI: URL编码后的回调地址（需与开放平台配置一致）
• STATE: 防CSRF攻击的随机字符串

---

三、后端处理：获取用户信息（Node.js示例）

1. 接收授权码（回调接口）

// Express 回调接口
app.get('/callback', (req, res) => {
  const { code, state } = req.query;
  // 验证 state 防止CSRF
  if (state !== SESSION_STATE) return res.status(403).send('Invalid state');
  
  // 用 code 换取 access_token
  getAccessToken(code).then(userInfo => {
    // 用户信息处理（登录/注册逻辑）
    console.log("钉钉用户信息:", userInfo);
    res.redirect('/home'); // 跳转首页
  });
});

2. 换取 Access Token

async function getAccessToken(code) {
  const url = 'https://api.dingtalk.com/v1.0/oauth2/userAccessToken';
  const params = {
    clientId: 'DINGTALK_APP_KEY',
    clientSecret: 'DINGTALK_APP_SECRET',
    code,
    grantType: 'authorization_code'
  };

  const response = await axios.post(url, params);
  const { accessToken } = response.data;
  return getUserInfo(accessToken); // 下一步获取用户信息
}

3. 获取用户信息

async function getUserInfo(accessToken) {
  const url = 'https://api.dingtalk.com/v1.0/contact/users/me';
  const headers = { 'x-acs-dingtalk-access-token': accessToken };
  
  const response = await axios.get(url, { headers });
  return response.data; // 返回钉钉用户数据
}

返回的用户信息示例：

{
  "nick": "张三",
  "avatarUrl": "https://xxx.png",
  "openId": "dt_OPENID",     // 用户在当前应用内的唯一标识
  "unionId": "dt_UNIONID",   // 用户在钉钉开放平台账号下的唯一标识
  "email": "[email protected]",
  "stateCode": "86",
  "mobile": "13800138000"
}

---

四、关键安全措施

1. State 参数校验
   生成随机 state 存入 Session，回调时严格比对
2. HTTPS 强制要求
   钉钉要求回调地址必须为 HTTPS
3. 敏感信息存储
   AppSecret 必须放在服务端（严禁前端暴露）

---

五、常见错误排查

错误码	原因	解决方案
60011	网页授权域名未配置	检查开放平台回调域名设置
61005	AppKey/Secret 不正确	核对应用凭证
40029	无效的授权码 (code)	检查 code 是否过期或被重复使用

---

六、完整流程总结

用户 Web应用 钉钉服务 访问登录页 返回钉钉登录二维码 扫码确认登录 携带code跳转回调URL 用code换access_token 返回access_token 用token获取用户信息 返回用户数据 完成登录，创建本地会话 用户 Web应用 钉钉服务

通过以上步骤，即可实现钉钉扫码登录与企业账号体系的深度集成。