架构与系统设计 / 系统课时
商户身份认证
商户身份认证
开放接口不能只依赖商户传入的编号来判断身份,因为商户号本身不是秘密。本课将建立“商户号 + 应用标识 + 密钥”的认证模型,并实现请求签名、时间戳校验和随机数防重放,让平台能够确认调用方身份及请求完整性。
学习目标
- 能区分商户号、应用标识和密钥的职责
- 能按统一规则生成并验证请求签名
- 能通过时间戳、随机数和密钥管理降低重放与泄露风险
三类身份凭证
merchantNo 表示业务主体,例如一家企业或门店集团;appId 表示该商户下的具体接入应用,例如生产系统、测试系统或不同业务线;secretKey 是平台与应用共同持有的秘密,只用于签名和验签,不应直接出现在请求正文中。
一个商户可以拥有多个应用,每个应用独立分配密钥、权限和调用限额。这样即使某个应用密钥泄露,也可以单独停用,不必影响该商户的全部系统。
签名认证流程
调用方发送请求前,先对请求方法、路径、时间戳、随机数和请求体摘要进行规范化,再使用密钥计算签名。平台收到请求后,根据 merchantNo 和 appId 查询密钥,重复计算签名并进行恒定时间比较。

推荐将以下内容组成待签名字符串:
POST
/open-api/v1/payments
1722758400
8f12c9d7a201
4f6d8a1f0f2d8e75...五行依次表示 HTTP 方法、请求路径、Unix 秒级时间戳、随机数和请求体的 SHA-256 摘要。字段顺序、换行符和字符编码必须固定,否则调用方与平台会计算出不同签名。
生成签名
下面使用 Java 生成 HMAC-SHA256 签名。示例中的密钥和时间戳是用于复核结果的固定测试数据;真实请求应使用当前 Unix 秒值 <TIME>,并从安全配置或密钥管理系统读取密钥。
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
public class RequestSigner {
private static String sha256Hex(String body) throws Exception {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(body.getBytes(StandardCharsets.UTF_8));
return HexFormat.of().formatHex(hash);
}
private static String hmacSha256Hex(String data, String secretKey) throws Exception {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
return HexFormat.of().formatHex(mac.doFinal(data.getBytes(StandardCharsets.UTF_8)));
}
public static void main(String[] args) throws Exception {
String method = "POST";
String path = "/open-api/v1/payments";
String timestamp = "1722758400";
String nonce = "8f12c9d7a201";
String body = "{\"merchantOrderNo\":\"ORDER202608030001\",\"amount\":1050}";
String secretKey = "demo-secret-key";
String canonical = String.join("\n",
method,
path,
timestamp,
nonce,
sha256Hex(body));
System.out.println(hmacSha256Hex(canonical, secretKey));
}
}预期输出:
e05dd707a5e82effe04fa406fee92b23d07190e6ca1e45dde472db5222cab20d调用方将结果放入 X-Signature 请求头,同时携带 X-Merchant-No、X-App-Id、X-Timestamp 和 X-Nonce。平台必须使用收到的原始请求体字节计算摘要,不能先反序列化再重新生成 JSON,因为字段顺序和空格变化会导致摘要不同。
服务端验签顺序
服务端应先检查必需请求头,再查询应用状态和密钥,然后校验时间戳窗口、随机数是否重复,最后验证签名。这样可以尽早拒绝缺少凭证、已停用应用或明显过期的请求。
时间戳通常只允许与服务器时间相差数分钟,实际窗口应根据网络环境和风险等级设定。nonce 在有效时间窗口内必须唯一,可存入 Redis 并设置略长于时间窗口的过期时间。只有签名、时间戳和随机数全部通过,业务请求才允许继续执行。
认证失败时返回 HTTP 401,并使用稳定错误码区分原因:
{
"code": "INVALID_SIGNATURE",
"message": "request signature verification failed",
"data": null,
"requestId": "req-20260803-0001"
}该响应不应暴露“正确签名”“密钥是否存在”或内部计算细节,避免为攻击者提供额外信息。
密钥生命周期
密钥创建后只在必要时展示一次,平台数据库中应加密存储,日志中禁止打印完整值。密钥轮换时可以为同一应用短暂保留新旧两把密钥:先让商户切换到新密钥,再停止旧密钥,避免一次性切换造成业务中断。
应用还应绑定接口权限、来源限制和调用额度。认证只证明“请求来自持有密钥的一方”,不代表它可以访问所有接口。验签成功后仍需继续做授权校验,例如限制某个 appId 只能发起支付查询,不能提交退款。
常见错误
不要把 secretKey 放进 URL、JSON 正文或前端代码中,也不要只对部分业务字段签名,否则未签名字段可能被篡改。不要使用普通字符串相等比较签名,建议采用恒定时间比较,降低时序侧信道风险。更不能在验签失败后自动跳过认证继续执行业务。