手把手教你设计一个提供给三方调用的接口鉴权（含完整 Java + Spring Boot 实现）

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！

🧩 一、需求场景：为什么需要三方接口鉴权？

你的系统要开放 API 给外部合作伙伴（如：支付回调、数据同步、SaaS 集成），但必须确保：

• 调用方身份可信：不是谁都能随便调；
• 请求未被篡改：防止中间人攻击；
• 防止重放攻击：同一个请求不能反复用；
• 可追溯、可限流：知道是谁在调、调了多少次。

✅ 常见方案：API Key + 签名（Signature）机制
（比单纯 token 更安全，比 OAuth2 更轻量）

🔐 二、鉴权设计原理（核心三要素）

我们采用“时间戳 + 随机串 + 签名”模型：

🔑 签名算法（HMAC-SHA256）

原始字符串 = app_id + timestamp + nonce 签名 = HMAC-SHA256(原始字符串, secret_key)

💡secret_key只有你和合作方知道，绝不通过网络传输！

🛠️ 三、Spring Boot 完整实现

1. 添加依赖

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> <!-- 可选，用于拦截 --> </dependency> <dependency> <groupId>commons-codec</groupId> <artifactId>commons-codec</artifactId> </dependency>

2. 创建鉴权配置类（模拟数据库）

@Component public class ApiKeyStore { // 模拟：appId -> secret 映射（生产环境应查数据库或缓存） private static final Map<String, String> APP_SECRET_MAP = new HashMap<>(); static { APP_SECRET_MAP.put("partner_001", "secret_abc123xyz"); APP_SECRET_MAP.put("partner_002", "secret_def456uvw"); } public String getSecretByAppId(String appId) { return APP_SECRET_MAP.get(appId); } public boolean isValidAppId(String appId) { return APP_SECRET_MAP.containsKey(appId); } }

3. 签名工具类

import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; import java.util.Base64; public class SignUtil { public static String generateSign(String appId, long timestamp, String nonce, String secret) { String rawString = appId + timestamp + nonce; try { Mac mac = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKey = new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); mac.init(secretKey); byte[] hash = mac.doFinal(rawString.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(hash); // 返回 Base64 编码 } catch (Exception e) { throw new RuntimeException("签名失败", e); } } public static boolean verifySign(String appId, long timestamp, String nonce, String sign, String secret) { String expectedSign = generateSign(appId, timestamp, nonce, secret); return expectedSign.equals(sign); } }

4. 自定义注解（可选，用于标记需鉴权的接口）

@Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface RequireAuth { }

5. 拦截器实现鉴权逻辑

@Component public class AuthInterceptor implements HandlerInterceptor { @Autowired private ApiKeyStore apiKeyStore; // 请求有效期：5分钟（防重放） private static final long EXPIRE_TIME = 5 * 60 * 1000L; @Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { // 如果方法没加 @RequireAuth，跳过 if (!(handler instanceof HandlerMethod) || !((HandlerMethod) handler).hasMethodAnnotation(RequireAuth.class)) { return true; } String appId = request.getHeader("X-App-Id"); String timestampStr = request.getHeader("X-Timestamp"); String nonce = request.getHeader("X-Nonce"); String sign = request.getHeader("X-Sign"); // 1. 参数校验 if (StringUtils.isEmpty(appId) || StringUtils.isEmpty(timestampStr) || StringUtils.isEmpty(nonce) || StringUtils.isEmpty(sign)) { response.setStatus(HttpStatus.UNAUTHORIZED.value()); response.getWriter().write("{\"code\":401,\"msg\":\"Missing auth headers\"}"); return false; } long timestamp; try { timestamp = Long.parseLong(timestampStr); } catch (NumberFormatException e) { response.setStatus(HttpStatus.UNAUTHORIZED.value()); response.getWriter().write("{\"code\":401,\"msg\":\"Invalid timestamp\"}"); return false; } // 2. 检查时间戳是否过期 if (System.currentTimeMillis() - timestamp > EXPIRE_TIME) { response.setStatus(HttpStatus.UNAUTHORIZED.value()); response.getWriter().write("{\"code\":401,\"msg\":\"Request expired\"}"); return false; } // 3. 检查 appId 是否合法 if (!apiKeyStore.isValidAppId(appId)) { response.setStatus(HttpStatus.UNAUTHORIZED.value()); response.getWriter().write("{\"code\":401,\"msg\":\"Invalid app_id\"}"); return false; } // 4. 验证签名 String secret = apiKeyStore.getSecretByAppId(appId); if (!SignUtil.verifySign(appId, timestamp, nonce, sign, secret)) { response.setStatus(HttpStatus.UNAUTHORIZED.value()); response.getWriter().write("{\"code\":401,\"msg\":\"Invalid signature\"}"); return false; } // ✅ 鉴权通过 return true; } }

6. 注册拦截器

@Configuration public class WebConfig implements WebMvcConfigurer { @Autowired private AuthInterceptor authInterceptor; @Override public void addInterceptors(InterceptorRegistry registry) { registry.addInterceptor(authInterceptor).addPathPatterns("/api/**"); } }

7. 测试接口

@RestController @RequestMapping("/api") public class TestController { @RequireAuth @GetMapping("/data") public ResponseEntity<?> getData() { return ResponseEntity.ok("敏感数据返回成功！"); } }

🧪 四、三方如何调用？（示例）

假设合作方partner_001要调用/api/data：

// 第三方调用示例（Java） String appId = "partner_001"; String secret = "secret_abc123xyz"; // 他们自己保存 long timestamp = System.currentTimeMillis(); String nonce = UUID.randomUUID().toString().replace("-", ""); String sign = SignUtil.generateSign(appId, timestamp, nonce, secret); // 发起 HTTP 请求（用 OkHttp / HttpClient） HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("http://your-server.com/api/data")) .header("X-App-Id", appId) .header("X-Timestamp", String.valueOf(timestamp)) .header("X-Nonce", nonce) .header("X-Sign", sign) .GET() .build();

✅ 成功返回"敏感数据返回成功！"
❌ 任意参数错误 → 返回 401

❌ 五、反例 & 常见错误

反例 1：用明文 token 代替签名

GET /api/data?token=abc123

💥 风险：token 被截获后可无限重放！

反例 2：签名不包含时间戳

// ❌ 只用 appId + nonce 签名 String raw = appId + nonce;

💥 风险：攻击者可录制请求，反复重放！

反例 3：secret 通过接口下发

“我们先调一个接口获取 secret” —— 这等于把钥匙挂在门上！

✅ 正确做法：secret 必须线下交付（邮件、加密文档、面对面）。

⚠️ 六、增强建议（生产级）

🎯 七、总结

这套机制简单、高效、安全，适用于绝大多数 B2B 开放平台场景。

视频看了几百小时还迷糊？关注我，几分钟让你秒懂！