- 调用格式说明
- Postman模板使用说明
- 第三方小程序应用密钥使用说明
- 第三方小程序应用上传资源
- 第三方小程序应用上传资源V2
- 授权
- 域名
- 模板管理
- 代商家管理小程序
- 代商家入驻抖音开放平台
第三方小程序应用密钥使用说明
更新时间 2024-07-24 02:58:49
收藏
我的收藏针对开放平台对外开放的能力,制定了一套签名机制与规范,当且仅当鉴权认证通过之后,才允许执行相应的接口逻辑。签名算法目前应用在对安全要求非常高的场景,如涉及资金交易的场景。除此外,绝大部分其他场景不需要接入签名。
密钥介绍
鉴权认证机制采用
SHA256-RSA2048
实现。使用说明
在鉴权认证机制中,需要 4 个密钥,分别为
- •平台公钥:
每个「第三方小程序」对应的平台公钥是不一样的,平台公钥由「开放平台」负责生成,并告知小程序代开发服务商。
- •平台私钥:
每个「第三方小程序」对应的平台私钥是不一样的,平台私钥由「开放平台」负责生成和保存。
- •应用公钥:
「第三方小程序」的应用公钥由代开发服务商生成并上传到「开放平台」,可支持更换。
- •应用私钥:
「第三方小程序」的应用私钥由代开发服务商生成并保存,不能对外提供,可支持更换。
交互方式如下图所示
应用密钥
生成方式
应用公钥和私钥的生成方式可参考:
Shell复制$ openssl
OpenSSL> genrsa -out private_key.pem 2048
Generating RSA private key, 2048 bit long modulus
....................+++
...........................................................................+++
e is 65537 (0x10001)
OpenSSL> rsa -in private_key.pem -pubout -out public_key.pem
writing RSA key
OpenSSL> exit
$ ls
private_key.pem public_key.pem
public_key.pem
中的整个文本数据即为需要上传的公钥,包含----BEGIN PUBLIC KEY---
一直到---END PUBLIC KEY----
。注意: 第三方小程序应用私钥务必妥善保存,不能对外公开。 当发现应用私钥泄漏之后,应及时重新生成,并将第三方小程序新应用公钥上传到「服务商平台」。
上传方式
- 1.登录「抖音开放平台 - 服务商平台」,进入第三方小程序的「开发-开发配置」页。
- 2.在「密钥设置」处点击「添加应用公钥」,将生成的应用公钥上传,上传成功后,鉴权认证机制的前期准备工作就结束了。
平台公钥
第三方小程序的平台公钥和私钥由「开放平台」负责生成和保存,不同「第三方小程序」的平台公钥和私钥是不同的。
获取方式:登录「抖音开放平台 - 服务商平台」,进入第三方小程序的「开发-开发配置」页,平台公钥在「密钥设置」处展示。
规则说明
基本信息
API 请求必须使用 HTTPS。
数据格式
消息体数据交换格式为 JSON ,请求须设置 HTTP 头部。
JSON复制Content-Type: application/json
Accept: application/json
参数兼容性
鉴权认证与请求参数的顺序无关。
请求的唯一标示
「开放平台」会给每一个接收到的请求分配一个唯一标示,该标示包含在应答的 HTTP 头
x-tt-logid
中。 当需要「开放平台」帮助时,请提供请求的唯一标示,以便我们更快的定位到具体的请求。签名介绍
- •签名:
「开放平台」通过验证签名来保证请求的真实性和数据的完整性。
- •请求签名:
代开发服务商首先需要对 URL、消息体等关键数据进行拼接组合,使用应用私钥对组合后的数据进行
SHA256-RSA2048
签名。签名信息通过 HTTP 头Byte-Authorization
传递。 「开放平台」会拒绝没有携带签名或者签名验证不通过的请求。- •应答签名:
「开放平台」会执行签名验证成功的请求,并使用平台私钥对应答数据进行签名,签名的信息包含在 HTTP 头部。代开发服务商应拒绝没有携带签名信息的成功应答(HTTP 状态码为 2xx),应认为是被伪造的或被篡改的应答。
- •回调通知签名:
当能力接口涉及回调通知结果时,「开放平台」使用平台私钥对回调通知请求进行签名。签名的方法同应答签名的方法一致,代开发服 务商务必验证回调通知请求的签名信息。
开发指南
生成签名
代开发服务商应按照下述步骤生成请求的签名信息。
第一步:构造待签名串
待签名串一共有 5 行,每一行为一个参数。行尾以
\n
(换行符,ASCII 编码值为 0x0A)结束,包括最后一行。如果参数本身以\n
结束,也需要附加一个\n
。最终格式如下:js复制HTTP请求方法\n
URL\n
请求时间戳\n
请求随机串\n
请求报文主体\n
其中:
- •HTTP 请求方法
如:POST,GET,PUT 等。注意请使用大写。
- •URL
获取请求的绝对 URL,并去除域名部分得到参与签名的 URL。 去除域名后的部分,必须以斜杠字符
“/”
开头。 如果去除域名后的部分为空,则用单个斜杠字符“/”
来当作 URL 用于签名。 如果请求中有查询参数,URL 末尾应附加有'?'
和对应的查询字符串。 如Shell复制PATH=https://open.douyin.com/api/trade/v2/query URL 则为 /api/trade/v2/query
PATH=https://open.douyin.com/api/trade/v2/query?a=x URL 则为 /api/trade/v2/query?a=x
- •请求时间戳
发起请求时系统的当前时间戳,即格林威治时间 1970 年 01 月 01 日 00 时 00 分 00 秒(北京时间 1970 年 01 月 01 日 08 时 00 分 00 秒)起至现在的总秒数,作为请求时间戳。「开放平台」会拒绝处理一个小时之前发起的请求。
- •请求随机串
任意生成一个随机字符串,以保证相同时间相同参数发起的请求签名值不一样(我们推荐生成随机串算法如下:调用随机数函数生成,将得到的值转换为字符串)。
- •请求报文主体
获取请求中的请求报文主体(request body)。
- ◦请求方法为GET时,报文主体为空。
- ◦当请求方法为POST或PUT时,请使用JSON报文内容。
第二步:计算签名值
成功构造待签名串后,应使用第三方小程序应用私钥对待签名串进行
SHA256-RSA2048
签名,并对签名结果进行Base64
编码得到签名值。签名命令可参考:
Shell复制$ echo -n -e \
"POST\n/api/business/diamond/query\n1623934869\nDC10180A100073E70A48F195DA2AF2E6\n{\"appid\":\"ttxxx\",\"order_id\":\"xxx\"}\n" \
| openssl dgst -sha256 -sign private_key.pem | openssl base64 -A
得到签名值:
Shell复制nwd1L3wCX+01/TVTkILeovF1DtYeghC1VHjrcjTHVkh7+gRaONEQkC2Y72Mw8JdSnIyeAtyp/pDHzyKGywjVqv5+JOBEhQG1/pvwNHN49wD26qg3AJL4hXw0fMJSRiTQEV1MszwDLuaabvo/qM9OXL9KyYiEPwVJqYtzmho4cHXT6mYgzNOW1xt5d7RDf4QO74JI3i4dtk9Uj8svJTrrBabML6AUcqcx2OP/7xukdaUgPdPf+IqmMG6GC4n52LUDogcL5n/osLdfHg9l6kW5gDcDjBfNDaggz07QMPHGdVao7pnQ2ub7VqcFIuY6Q3cBL7ndQdDGKrv+WBy5Q90QjQ==
- •签名生成 Golang 代码示例,仅供参考:
Go复制func GenSign(method, url, timestamp, nonce, body string, privateKey *rsa.PrivateKey) (string, error) {
//组装被加密的字符串
targetStr := method + "\n" + url + "\n" + timestamp + "\n" + nonce + "\n" + body + "\n"
//加密
h := sha256.New()
h.Write([]byte(targetStr))
digestBytes := h.Sum(nil)
signBytes, err := rsa.SignPKCS1v15(rand.Reader, privateKey, crypto.SHA256, digestBytes)
if err != nil {
return "", err
}
sign := base64.StdEncoding.EncodeToString(signBytes)
return sign, nil
}
- •签名生成 PHP 代码示例,仅供参考:
PHP复制public function makeSign($method, $url, $body, $timestamp, $nonce_str) {
$text = $method . "\n" . $url . "\n" . $timestamp . "\n" . $nonce_str . "\n" . $body . "\n";
$priKey = file_get_contents("/private_key.pem");
$privateKey = openssl_get_privatekey($priKey, '');
openssl_sign($text, $sign, $privateKey, OPENSSL_ALGO_SHA256);
$sign = base64_encode($sign);
return $sign;
}
- •签名生成 Java 示例,仅供参考:
Java复制public static String getSignature(String privateKeyStr, String method, String url, String body) throws Exception {
Long timestamp = getTime();
String nonce = getNonce();
StringBuffer buffer = new StringBuffer();
buffer.append(method).append("\n");
buffer.append(url).append("\n");
buffer.append(timestamp).append("\n");
buffer.append(nonce).append("\n");
buffer.append(body).append("\n");
Signature sign = Signature.getInstance("SHA256withRSA");
sign.initSign(string2PrivateKey(privateKeyStr));
sign.update(buffer.toString().getBytes(StandardCharsets.UTF_8));
return Base64.getEncoder().encodeToString(sign.sign());
}
// string2PrivateKey 仅供参考
public static PrivateKey string2PrivateKey(String privateKeyStr) {
PrivateKey prvKey = null;
try {
byte[] privateBytes = Base64.getDecoder().decode(privateKeyStr);
PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(privateBytes);
KeyFactory keyFactory = KeyFactory.getInstance(“RSA”);
prvKey = keyFactory.generatePrivate(keySpec);
} catch (Exception ex) {
ex.printStackTrace();
}
return prvKey;
}
第三步:设置 HTTP Header
签名信息通过 HTTP 头
Byte-Authorization
传递,Byte-Authorization
由认证类型和签名信息两部分组成。Shell复制Byte-Authorization: 认证类型 签名信息
- •认证类型:
目前为
SHA256-RSA2048
- •签名信息:
- ◦授权小程序应用
appid
- ◦请求随机串
nonce_str
- ◦