视频看了几百小时还迷糊？关注我，几分钟让你秒懂！
🧩 一、需求场景：为什么需要三方接口鉴权？
你的系统要开放 API 给外部合作伙伴（如：支付回调、数据同步、SaaS 集成），但必须确保：
- 调用方身份可信：不是谁都能随便调；
- 请求未被篡改：防止中间人攻击；
- 防止重放攻击：同一个请求不能反复用；
- 可追溯、可限流：知道是谁在调、调了多少次。
✅ 常见方案：API Key + 签名（Signature）机制
（比单纯 token 更安全，比 OAuth2 更轻量）
🔐 二、鉴权设计原理（核心三要素）
我们采用“时间戳 + 随机串 + 签名”模型：
| 参数 | 说明 |
|---|---|
app_id | 分配给第三方的唯一标识（如：partner_001） |
timestamp | 当前 Unix 时间戳（毫秒），用于防重放 |
nonce | 随机字符串（如 UUID），避免重复请求 |
sign | 签名值，由app_id + timestamp + nonce + secret计算得出 |
🔑 签名算法（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 必须线下交付（邮件、加密文档、面对面）。
⚠️ 六、增强建议（生产级）
| 问题 | 解决方案 |
|---|---|
| 高频调用 | 增加 Redis 记录nonce，防止 5 分钟内重复使用 |
| 密钥轮换 | 支持secret_v1/secret_v2双版本过渡 |
| IP 白名单 | 结合X-Forwarded-For限制来源 IP |
| 审计日志 | 记录每次调用的appId、IP、接口、时间 |
| 限流 | 用 Guava RateLimiter 或 Sentinel 按appId限流 |
🎯 七、总结
| 要素 | 作用 |
|---|---|
app_id | 标识调用方 |
timestamp | 防重放（时效性） |
nonce | 防重复（唯一性） |
sign | 防篡改（完整性） |
secret | 共享密钥（保密性） |
这套机制简单、高效、安全，适用于绝大多数 B2B 开放平台场景。
视频看了几百小时还迷糊？关注我，几分钟让你秒懂！
