4. 接口安全设计：API密钥、OAuth2.0、IP白名单、请求签名机制

商户风险评分API承载着敏感的交易与商户数据，接口安全是整体设计的基石。本章围绕四层纵深防御体系展开：API密钥用于身份标识，OAuth2.0用于授权委托，IP白名单用于网络边界控制，请求签名机制用于数据完整性校验。四者协同，构建从传输层到应用层的完整防护。

4.1 API密钥（API Key）

API密钥是调用方身份的静态凭证，通常由服务端颁发的一对字符串（AppKey + AppSecret）。AppKey用于标识调用方身份，AppSecret用于签名计算，不应在网络中明文传输。

4.2 OAuth2.0 授权委托

当第三方系统需要代表商户访问风险评分API时，OAuth2.0提供了安全的授权委托机制。本接口推荐使用客户端凭证模式（Client Credentials Grant），适用于服务器到服务器的场景。

4.3 IP白名单

IP白名单是网络层的访问控制手段，仅允许预设的IP地址或IP段访问API。对于服务端API，这是阻断未授权请求的第一道防线。

4.4 请求签名机制

请求签名机制用于验证请求的完整性、真实性和防重放攻击。商户使用AppSecret对请求参数进行签名，服务端使用相同的密钥和算法进行校验。

4.4.1 签名算法流程

4.4.2 签名参数规范

4.4.3 签名生成示例（Java）

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;
import java.util.TreeMap;

public class SignUtil {
    public static String generateSign(TreeMap<String, String> params, String appSecret) throws Exception {
        // 1. 按字典序拼接参数
        StringBuilder sb = new StringBuilder();
        for (Map.Entry<String, String> entry : params.entrySet()) {
            sb.append(entry.getKey()).append("=").append(entry.getValue()).append("&");
        }
        sb.deleteCharAt(sb.length() - 1);
        
        // 2. 拼接AppSecret
        String stringToSign = sb.toString() + appSecret;
        
        // 3. HMAC-SHA256 计算
        Mac mac = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(appSecret.getBytes("UTF-8"), "HmacSHA256");
        mac.init(secretKey);
        byte[] hash = mac.doFinal(stringToSign.getBytes("UTF-8"));
        
        // 4. Base64编码
        return Base64.getEncoder().encodeToString(hash);
    }
}

4.4.4 服务端校验逻辑

public boolean verifySign(HttpRequest request, String appSecret) {
    // 1. 提取参数
    String timestamp = request.getHeader("timestamp");
    String nonce = request.getHeader("nonce");
    String sign = request.getHeader("sign");
    
    // 2. 时间戳校验（±5分钟）
    long now = System.currentTimeMillis();
    if (Math.abs(now - Long.parseLong(timestamp)) > 300000) {
        return false; // 请求过期
    }
    
    // 3. nonce去重（Redis缓存，有效期5分钟）
    if (redis.exists("nonce:" + nonce)) {
        return false; // 重复请求
    }
    redis.setex("nonce:" + nonce, 300, "1");
    
    // 4. 重新计算签名并比对
    TreeMap<String, String> params = extractParams(request);
    String expectedSign = SignUtil.generateSign(params, appSecret);
    return expectedSign.equals(sign);
}

4.5 四层安全机制协同