架构与系统设计 / 系统课时

商户身份认证

商户身份认证

开放接口不能只依赖商户传入的编号来判断身份,因为商户号本身不是秘密。本课将建立“商户号 + 应用标识 + 密钥”的认证模型,并实现请求签名、时间戳校验和随机数防重放,让平台能够确认调用方身份及请求完整性。

学习目标

  • 能区分商户号、应用标识和密钥的职责
  • 能按统一规则生成并验证请求签名
  • 能通过时间戳、随机数和密钥管理降低重放与泄露风险

三类身份凭证

merchantNo 表示业务主体,例如一家企业或门店集团;appId 表示该商户下的具体接入应用,例如生产系统、测试系统或不同业务线;secretKey 是平台与应用共同持有的秘密,只用于签名和验签,不应直接出现在请求正文中。

一个商户可以拥有多个应用,每个应用独立分配密钥、权限和调用限额。这样即使某个应用密钥泄露,也可以单独停用,不必影响该商户的全部系统。

签名认证流程

调用方发送请求前,先对请求方法、路径、时间戳、随机数和请求体摘要进行规范化,再使用密钥计算签名。平台收到请求后,根据 merchantNo 和 appId 查询密钥,重复计算签名并进行恒定时间比较。

商户请求签名与平台验签时序

推荐将以下内容组成待签名字符串:

text
POST
/open-api/v1/payments
1722758400
8f12c9d7a201
4f6d8a1f0f2d8e75...

五行依次表示 HTTP 方法、请求路径、Unix 秒级时间戳、随机数和请求体的 SHA-256 摘要。字段顺序、换行符和字符编码必须固定,否则调用方与平台会计算出不同签名。

生成签名

下面使用 Java 生成 HMAC-SHA256 签名。示例中的密钥和时间戳是用于复核结果的固定测试数据;真实请求应使用当前 Unix 秒值 <TIME>,并从安全配置或密钥管理系统读取密钥。

java
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));
    }
}

预期输出:

text
e05dd707a5e82effe04fa406fee92b23d07190e6ca1e45dde472db5222cab20d

调用方将结果放入 X-Signature 请求头,同时携带 X-Merchant-No、X-App-Id、X-Timestamp 和 X-Nonce。平台必须使用收到的原始请求体字节计算摘要,不能先反序列化再重新生成 JSON,因为字段顺序和空格变化会导致摘要不同。

服务端验签顺序

服务端应先检查必需请求头,再查询应用状态和密钥,然后校验时间戳窗口、随机数是否重复,最后验证签名。这样可以尽早拒绝缺少凭证、已停用应用或明显过期的请求。

时间戳通常只允许与服务器时间相差数分钟,实际窗口应根据网络环境和风险等级设定。nonce 在有效时间窗口内必须唯一,可存入 Redis 并设置略长于时间窗口的过期时间。只有签名、时间戳和随机数全部通过,业务请求才允许继续执行。

认证失败时返回 HTTP 401,并使用稳定错误码区分原因:

json
{
  "code": "INVALID_SIGNATURE",
  "message": "request signature verification failed",
  "data": null,
  "requestId": "req-20260803-0001"
}

该响应不应暴露“正确签名”“密钥是否存在”或内部计算细节,避免为攻击者提供额外信息。

密钥生命周期

密钥创建后只在必要时展示一次,平台数据库中应加密存储,日志中禁止打印完整值。密钥轮换时可以为同一应用短暂保留新旧两把密钥:先让商户切换到新密钥,再停止旧密钥,避免一次性切换造成业务中断。

应用还应绑定接口权限、来源限制和调用额度。认证只证明“请求来自持有密钥的一方”,不代表它可以访问所有接口。验签成功后仍需继续做授权校验,例如限制某个 appId 只能发起支付查询,不能提交退款。

常见错误

不要把 secretKey 放进 URL、JSON 正文或前端代码中,也不要只对部分业务字段签名,否则未签名字段可能被篡改。不要使用普通字符串相等比较签名,建议采用恒定时间比较,降低时序侧信道风险。更不能在验签失败后自动跳过认证继续执行业务。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

商户身份认证

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通