鉴权说明

鉴权说明

1. 引言

本文档旨在指导如何对接单多啦系统的API接口。对接过程中，需要对HTTP请求进行签名计算，以确保请求的合法性和安全性。

2. 接口对接流程

2.1 获取访问密钥

1. 在收单机后台创建租户。
2. 在菜单【接口应用】新建应用，选择类型：三方接口。
3. 应用创建后，直接复制AppID和AppSecret。若密钥泄露，应立即重置。

2.2 创建规范请求

为了在HTTP请求中进行身份验证，需要在请求头信息中添加authorization字段。authorization由以下几部分组成：

1. AppID：由单多啦系统颁发的，用于标识请求来源的应用的唯一标识符。
2. 时间戳（time）：当前的时间戳，以毫秒为单位，用于确保请求的时效性。
3. UUID：一个36位的字符串，用于唯一标识每一次请求，防止请求被重复处理。
4. 请求行（request-line）：HTTP请求的方法和路径，如POST /v2/ddl/api/xxxx。

这些信息按照特定的格式拼接后，使用HMAC-SHA256算法和AppSecret进行签名，得到签名后的摘要signature_sha。然后，将拼接好的原始签名信息authorization_origin进行Base64编码，形成最终的authorization值。

2.3 构建 authorization

以下是构造authorization字段的步骤：

graph TD
     B[拼接原始签名信息]
    B --> C[HMAC-SHA256加密签名]
    C --> D[拼接Authorization字段]
    D --> E[Base64编码Auth]
    E --> F[设置HTTP请求头]
    

1. 拼接原始签名信息（signature_origin）

signature_origin由 uuid，time，request-line三个参数按照格式拼接成，拼接的格式为(\n为换行符,’:’后面有一个空格)

signature_origin = "apiKey:uuid:time:request-line"

2. 使用AppSecret进行HMAC-SHA256签名

   signature_sha = hmac-sha256(signature_origin, AppSecret)
   

3. 拼接Authorization字段

   authorization_origin = "apiKey:uuid:time:signature_sha"
   

4. Base64编码

authorization = base64(authorization_origin)

5. 设置HTTP请求头

headers['authorization'] = authorization

3. 参考代码

以下是Java的示例代码：

/**
 *生成签名
 *
@param method 如 POST
@param uri /v2/cabinet/client/test
@param secret
 @param uuid
 @param time 时间戳字符串 毫秒
 @return
 */
public static String createSign(String method, String uri, String uuid, String time, String secret) {
    String signOrigin = "uuid: " uuid + "\ntime: " time + "\n" method + " " uri + "\n";
    String sign = hmacSHA256Encode(secret, signOrigin);
    return sign;
}

/**
生成请求头认证字符串
 *
@param method
 @param uri
 @param appKey
 @param secret
 @return
 */
public static String createAuthorization(String method, String uri, String appKey, String secret) {
    String uuid = UUID.randomUUID().toString();
    String time = String.valueOf(System.currentTimeMillis());
    String sign = createSign(method, uri, uuid, time, secret);
    SignModelBean build = SignModelBean.builder()
            .signature(sign)
            .time(time)
            .uuid(uuid)
            .appKey(appKey)
            .build();
    return Base64.encode(build.toString());
}

/**
sha256_HMAC加密
 *
@param secret  秘钥
 @param message 消息
 @return 加密后字符串
 */
public static String hmacSHA256Encode(String secret, String message) {
    String rs = null;
    try {
        Mac hmacSha256 = Mac.getInstance(SIGN_METHOD);
        SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), SIGN_METHOD);
        hmacSha256.init(secret_key);
        bytebytes = hmacSha256.doFinal(message.getBytes());
        rs = byteArrayToHexString(bytes);
    } catch (Exception e) {
        e.printStackTrace();
    }
    return rs;
}