HMAC Auth 鉴权说明

HMAC Auth（Hash-based Message Authentication Code）是一种基于 共享密钥 + 请求签名 的接口鉴权方式。

客户端使用 Secret Key 对请求的关键内容进行 HMAC 哈希计算生成签名，并随请求发送到服务器。服务器使用相同的 Secret Key 重新计算签名并进行比对，从而验证请求是否来自合法客户端并且未被篡改。([Kong Docs][1])

该方式具有以下优点：

不需要额外获取 token

可以防止请求被篡改

可防止重放攻击

适合 Server-to-Server API 调用

一、鉴权流程

HMAC Auth 的基本流程如下：

平台为每个客户端分配：

username（Access Key）

secret（Secret Key）

客户端在请求 API 时：

构造签名字符串

使用 Secret Key 计算 HMAC 签名

将签名信息放入 Authorization 请求头

服务器：

根据 username 找到对应 secret

重新计算签名

对比签名是否一致

如果一致，则请求合法。

二、请求头格式

客户端必须在请求中携带 Authorization 头。

Authorization: hmac username="ACCESS_KEY", algorithm="hmac-sha256", headers="date @request-target", signature="BASE64_SIGNATURE"

字段说明：

参数	类型	说明
username	string	客户端 Access Key
algorithm	string	HMAC 算法
headers	string	参与签名的 Header 列表
signature	string	Base64 编码后的签名

支持算法：

hmac-sha1
hmac-sha256
hmac-sha384
hmac-sha512

推荐使用：

hmac-sha256

三、参与签名的 Header

签名时需要指定参与计算的 header，例如：

headers="date @request-target"

推荐最少包含：

@request-target
host
date

示例：

headers="date host @request-target"

服务器和客户端必须 使用相同顺序 计算签名。 ([Kong Docs][2])

四、签名字符串构造规则

签名字符串由 headers 指定的字段按顺序拼接。

规则：

1️⃣ header 名称全部使用小写
2️⃣ header 与值之间使用 :
3️⃣ 多个 header 之间使用 \n

示例

请求：

GET /v1/user?id=123 HTTP/1.1
Host: api.example.com
Date: Tue, 12 Mar 2026 10:00:00 GMT

headers 定义：

headers="date @request-target"

生成的签名字符串：

date: Tue, 12 Mar 2026 10:00:00 GMT
@request-target: get /v1/user?id=123

注意：

@request-target 格式为

<method_lowercase> <path_and_query>

示例：

get /v1/user?id=123

五、生成签名

使用 Secret Key 计算 HMAC：

signature = Base64(
    HMAC-SHA256(
        signing_string,
        secret
    )
)

示例：

base64(hmac_sha256(signing_string, secret))

六、完整请求示例

GET /v1/user?id=123 HTTP/1.1
Host: api.example.com
Date: Tue, 12 Mar 2026 10:00:00 GMT

Authorization: hmac username="demo-client",
algorithm="hmac-sha256",
headers="date @request-target",
signature="mF8F4F3iKQm9R0oU1Y7rj3u0oKkM4sH5c5k7G2Lq="

七、请求体签名（可选）

如果接口包含请求体，可以增加 Digest 头用于验证请求体完整性。([Kong Docs][1])

Digest 计算方式：

Digest: SHA-256=Base64(SHA256(body))

示例：

Digest: SHA-256=SBH7QEtqnYUpEcIhDbmStNd1MxtHg2+feBfWc1105MA=

然后在 headers 中加入：

headers="date @request-target digest"

八、防止重放攻击

客户端必须发送：

Date

或

X-Date

服务器会验证时间差。

默认允许：

±300 秒

超过时间范围的请求将被拒绝。 ([Kong Docs][1])

九、鉴权失败示例

可能返回：

401 Unauthorized

常见原因：

原因	说明
signature 不正确	签名计算错误
headers 顺序不一致	签名字符串不一致
时间超出范围	防重放校验失败
Access Key 不存在	username 无效

十、Python 示例

十一、最佳实践

建议：

必须签名字段

@request-target
host
date

推荐签名字段

@request-target
host
date
digest
content-type

安全建议：

Secret Key 必须安全存储

使用 HTTPS 传输

定期轮换 Secret Key

HMAC Auth

HMAC Auth 鉴权说明#

一、鉴权流程#

二、请求头格式#

三、参与签名的 Header#

四、签名字符串构造规则#

示例#

五、生成签名#

六、完整请求示例#

七、请求体签名（可选）#

八、防止重放攻击#

九、鉴权失败示例#

十、Python 示例#

十一、最佳实践#