当前位置：首页 > news >正文

实战案例：Spring Boot 快实现钉钉扫码登录（不需要企业认证）

news 2026/5/13 13:26:58

前置条件，准备clientid、clientsecrect密钥、回调地址即可（本地需要自备公网映射）。

实战案例：Spring Boot 快实现钉钉扫码登录

在企业级 OA 系统或内部工具开发中，“钉钉扫码登录”是最高频的需求之一。它能利用钉钉的身份认证体系，免去用户记忆账号密码的烦恼，同时实现企业架构的安全管控。

本文基于Spring Boot 2.x和阿里新版 Tea SDK (2.0)，还原从配置到代码落地的完整流程，重点解决403权限报错和SDK参数类型不匹配等痛点。

一、核心准备工作 (不做必错)

在写代码之前，必须先在钉钉开发者后台完成以下配置。****

1. 权限开通 (关键！)

痛点：代码跑通了，但最后一步获取用户信息时报错 403 Forbidden。

原因：未开通通讯录读取权限。

解决：

进入【应用开发】->【权限管理】，搜索并申请以下权限：

✅通讯录个人信息读权限(核心：用于获取UnionId和Nick，不申请会报 403)
✅成员信息读权限(建议一并申请)

2. 配置回调域名

规则：前端代码里的redirect_uri必须与后台配置字符级完全一致。

开发配置->回调域名：
- 示例：http://domain.com:28088/login/callback# 回调你本地或公网的
- 注意：请确保包含http://协议头和端口号。

二、项目依赖配置 (Maven)

<dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>com.aliyun</groupId> <artifactId>dingtalk</artifactId> <version>2.2.40</version> </dependency> <dependency> <groupId>com.aliyun</groupId> <artifactId>tea-openapi</artifactId> <version>0.3.1</version> </dependency> <dependency> <groupId>com.aliyun</groupId> <artifactId>tea-util</artifactId> <version>0.2.16</version> </dependency> </dependencies>

三、前端实现 (内嵌二维码)

使用钉钉官方提供的ddlogin.js，可以在页面内通过div容器直接渲染二维码，无需跳转页面，体验更佳。

文件：index.html

HTML

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="UTF-8"> <title>OA系统钉钉扫码登录</title> <script src="https://g.alicdn.com/dingding/h5-dingtalk-login/0.21.0/ddlogin.js"></script> <style> body { display: flex; justify-content: center; align-items: center; height: 100vh; background: #f0f2f5; } #login_box { background: #fff; padding: 20px; border-radius: 8px; box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); } </style> </head> <body> <div id="login_box"></div> <script> // 必须与钉钉后台配置的一模一样 const REDIRECT_URI = "http://domain.com:28088/login/callback"; const CLIENT_ID = "dingw6c***sfqjrr"; // 您的ClientId window.DTFrameLogin( { id: 'login_box', width: 300, height: 300, }, { redirect_uri: REDIRECT_URI, client_id: CLIENT_ID, scope: 'openid', // 固定值 response_type: 'code', // 固定值 state: 'my_oa_security_token', // 防止CSRF，生产环境建议随机生成 prompt: 'consent', }, (loginResult) => { // 扫码成功后，钉钉返回 redirectUrl，其中包含了 authCode window.location.href = loginResult.redirectUrl; }, (errorMsg) => { alert("二维码加载失败: " + JSON.stringify(errorMsg)); } ); </script> </body> </html>

四、后端实现 (核心逻辑)

后端逻辑遵循“Code 换 Token -> Token 换 UserInfo”的标准流程。

package org.example.dingdingscan; import com.aliyun.teaopenapi.models.Config; import com.aliyun.dingtalkoauth2_1_0.Client; import com.aliyun.dingtalkoauth2_1_0.models.*; import com.aliyun.dingtalkcontact_1_0.models.*; import com.aliyun.teautil.models.RuntimeOptions; // 必须引入 import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/login") public class DingLoginController { // 替换为您的真实配置 private static final String CLIENT_ID = "dingw6cv1****fqjrr"; private static final String CLIENT_SECRET = "uiGdvr7xztEU****uLgmSv0O1nOiPoe0-vmkfYWHxMDAeiDIv42QEFY"; @GetMapping("/callback") public String callback(@RequestParam("authCode") String authCode) { try { // --- 步骤 1：初始化基础配置 --- Config config = new Config(); config.protocol = "https"; config.regionId = "central"; // --- 步骤 2：使用 OAuth2 Client 获取 AccessToken --- Client oauthClient = new Client(config); GetUserTokenRequest tokenRequest = new GetUserTokenRequest() .setClientId(CLIENT_ID) .setClientSecret(CLIENT_SECRET) .setCode(authCode) .setGrantType("authorization_code"); GetUserTokenResponse tokenResponse = oauthClient.getUserToken(tokenRequest); String userAccessToken = tokenResponse.getBody().getAccessToken(); // --- 步骤 3：使用 Contact Client 获取用户信息 --- com.aliyun.dingtalkcontact_1_0.Client contactClient = new com.aliyun.dingtalkcontact_1_0.Client(config); GetUserHeaders headers = new GetUserHeaders(); headers.setXAcsDingtalkAccessToken(userAccessToken); // 【核心修正点】使用 WithOptions 避免参数类型报错 GetUserResponseBody userBody = contactClient.getUserWithOptions( "me", // "me" 代表查询当前用户 headers, new RuntimeOptions() // 运行时参数，不可为 null ).getBody(); // --- 步骤 4：提取核心数据 --- String dingUserId = userBody.getUnionId(); // 全局唯一ID String nick = userBody.getNick(); String avatar = userBody.getAvatarUrl(); // 在此处对接您的 OA 数据库： // select * from sys_user where union_id = dingUserId return "<div style='text-align:center; padding:50px;'>" + "<h2>🎉 登录成功</h2>" + "<img src='" + avatar + "' style='width:64px;border-radius:50%;'><br/>" + "<b>欢迎回来:</b> " + nick + "<br/>" + "<b>UnionId:</b> " + dingUserId + "</div>"; } catch (Exception e) { e.printStackTrace(); return "❌ 登录失败: " + e.getMessage(); // 常见错误如 403 会在这里捕获 } } }

五、总结与排查速查表

在整个实施过程中，请对照以下表格自查：

错误现象	可能原因	解决方案
二维码加载不出来	前端`client_id`或`redirect_uri`配置错误	检查代码与钉钉后台【回调域名】是否完全一致。
Code: 403 Forbidden	接口权限未开通	钉钉后台 -> 权限管理 -> 申请“通讯录个人信息读权限”。
Maven 找不到包	依赖版本过旧或模块拆分错误	使用`dingtalk`聚合包，版本推荐`2.2.40`。
Required String…	SDK 方法签名不匹配	改用`getUserWithOptions`替代`getUser`。
手机号为空	企业未认证	未认证企业通常无法通过 API 获取手机号，建议使用`UnionId`做账号绑定。