如何通过API获取创建DocuSign Connect时生成的HMAC密钥？

一、获取HMAC密钥的两种方式 #

1. 创建Connect时直接提取响应结果 #

当你调用Java SDK的createConnectConfiguration方法创建Connect，并设置includeHMAC为true后，DocuSign的响应对象ConnectConfiguration会直接返回生成的HMAC密钥，字段名为hmacSecret。示例代码：

// 假设已构建好connectConfig并开启includeHMAC
ConnectConfiguration createdConfig = envelopesApi.createConnectConfiguration(accountId, connectConfig);
String hmacSecret = createdConfig.getHmacSecret();
// 务必将密钥加密存储，避免明文泄露

2. 后续查询已存在的Connect配置 #

如果创建时未保存密钥，可通过getConnectConfiguration接口查询指定的Connect配置，响应中同样会包含hmacSecret字段：

ConnectConfiguration existingConfig = envelopesApi.getConnectConfiguration(accountId, connectConfigId);
String hmacSecret = existingConfig.getHmacSecret();

注意：HMAC密钥仅在创建和查询接口的响应中返回，DocuSign不会重复发送，首次获取后必须妥善存储。

二、验证DocuSign请求的核心逻辑 #

拿到密钥后，验证流程如下：

• 从请求头中提取X-DocuSign-Signature字段值
• 使用请求原始body（字节流）结合HMAC密钥，以HMAC-SHA256算法生成签名
• 将生成的签名转为Base64编码，与请求头中的签名值对比，一致则验证通过

Java验证示例：

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

public boolean verifyDocusignRequest(String rawRequestBody, String signatureHeader, String hmacSecret) {
    try {
        Mac hmacSha256 = Mac.getInstance("HmacSHA256");
        SecretKeySpec secretKey = new SecretKeySpec(hmacSecret.getBytes(), "HmacSHA256");
        hmacSha256.init(secretKey);
        byte[] signatureBytes = hmacSha256.doFinal(rawRequestBody.getBytes());
        String generatedSignature = Base64.getEncoder().encodeToString(signatureBytes);
        return generatedSignature.equals(signatureHeader);
    } catch (Exception e) {
        // 处理密钥无效、算法不支持等异常
        return false;
    }
}

三、关键注意事项 #

• 存储HMAC密钥必须用加密手段，禁止明文存储
• 验证时必须使用原始请求body，不能做任何格式化、编码转换操作，否则签名会不匹配
• 若更新Connect配置时再次设置includeHMAC: true，会生成新密钥，旧密钥立即失效，需同步更新本地存储的密钥

内容的提问来源于stack exchange，提问作者Vineel Pellella