API7 网关 AI Agent Skill：hmac-auth 插件

概览

hmac-auth 插件使用 HMAC（Hash-based Message Authentication Code）签名对请求进行身份认证。客户端会基于请求方法、路径、日期以及可选请求头/请求体计算 HMAC 签名，然后将其放入 Authorization 请求头中。API7 企业版会在服务端重新计算签名并校验其是否匹配。这种方式无需在线路上传输密钥，即可验证请求完整性。

适用场景

• 请求完整性校验（防止 API 调用被篡改）
• 适用于双方共享密钥的服务间身份认证
• 需要校验请求体完整性的 API
• 令牌或密码不应出现在请求中的环境

插件配置参考（路由/服务）

字段	类型	是否必填	默认值	说明
allowed_algorithms	array	否	["hmac-sha1","hmac-sha256","hmac-sha512"]	允许使用的 HMAC 算法
clock_skew	integer	否	300	客户端与服务端之间允许的最大时间差，单位秒
signed_headers	array	否	—	HMAC 签名中要求包含的额外请求头
validate_request_body	boolean	否	false	通过 SHA-256 摘要校验请求体完整性
hide_credentials	boolean	否	false	转发到上游前移除 Authorization 请求头
anonymous_consumer	string	否	—	未通过身份认证的请求所使用的消费者用户名
realm	string	否	"hmac"	WWW-Authenticate 响应头中的 Realm

消费者凭证参考

字段	类型	是否必填	说明
key_id	string	是	消费者的唯一标识符
secret_key	string	是	用于 HMAC 计算的密钥，会在数据库中自动加密

分步操作：在路由上启用 hmac-auth

1. 创建消费者

a7 consumer create -g default -f - <<'EOF'
{
  "username": "alice"
}
EOF

2. 添加 hmac-auth 凭证

curl -k "https://$(a7 context current -o json | jq -r .server):7443/apisix/admin/consumers/alice/credentials" \
  -X PUT \
  -H "X-API-KEY: $(a7 context current -o json | jq -r .token)" \
  -d '{
    "id": "cred-alice-hmac",
    "plugins": {
      "hmac-auth": {
        "key_id": "alice-key",
        "secret_key": "alice-secret-key-value"
      }
    }
  }'

3. 创建启用 hmac-auth 的路由

a7 route create -g default -f - <<'EOF'
{
  "id": "hmac-protected",
  "uri": "/api/*",
  "plugins": {
    "hmac-auth": {}
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

4. 生成签名并测试

HMAC 签名遵循 HTTP Signatures 草案。

Python 示例：

import hmac, hashlib, base64
from datetime import datetime, timezone

key_id = "alice-key"
secret_key = b"alice-secret-key-value"
method = "GET"
path = "/api/users"
algorithm = "hmac-sha256"

gmt_time = datetime.now(timezone.utc).strftime('%a, %d %b %Y %H:%M:%S GMT')

signing_string = f"{key_id}\n{method} {path}\ndate: {gmt_time}\n"

signature = base64.b64encode(
    hmac.new(secret_key, signing_string.encode(), hashlib.sha256).digest()
).decode()

# 请求中使用以下请求头：
# Date: {gmt_time}
# Authorization: Signature keyId="{key_id}",algorithm="{algorithm}",
#   headers="@request-target date",signature="{signature}"

curl 示例：

curl -i http://127.0.0.1:9080/api/users \
  -H "Date: $(date -u +'%a, %d %b %Y %H:%M:%S GMT')" \
  -H 'Authorization: Signature keyId="alice-key",algorithm="hmac-sha256",headers="@request-target date",signature="<computed_signature>"'

Authorization 请求头格式

Signature keyId="{key_id}",algorithm="{algorithm}",headers="{signed_headers}",signature="{signature}"

组件	说明
keyId	消费者的 key_id 值
algorithm	hmac-sha1、hmac-sha256、hmac-sha512 之一
headers	以空格分隔的列表：@request-target date [additional...]
signature	Base64 编码的 HMAC 签名

签名字符串构造

签名字符串以换行分隔：

{key_id}\n
{METHOD} {path}\n
date: {Date header value}\n
{additional-header}: {value}\n

• 第一行：key_id
• 第二行：HTTP 方法 + 空格 + 请求路径
• 后续行：小写请求头名称及其值
• 每一行都以 \n 结束

常见模式

限制为指定算法

{
  "plugins": {
    "hmac-auth": {
      "allowed_algorithms": ["hmac-sha256", "hmac-sha512"]
    }
  }
}

增大时钟偏差容忍度

{
  "plugins": {
    "hmac-auth": {
      "clock_skew": 600
    }
  }
}

允许最多 10 分钟的时间差。

校验请求体

{
  "plugins": {
    "hmac-auth": {
      "validate_request_body": true
    }
  }
}

客户端必须包含 Digest: SHA-256={base64_sha256_of_body} 请求头。API7 企业版会重新计算请求体摘要；如果不匹配，则拒绝请求。

要求签名包含自定义请求头

{
  "plugins": {
    "hmac-auth": {
      "signed_headers": ["x-custom-header-a", "x-custom-header-b"]
    }
  }
}

添加到上游的请求头

请求头	值
X-Consumer-Username	消费者用户名
X-Credential-Identifier	凭证 ID
X-Consumer-Custom-Id	消费者的 labels.custom_id（如已设置）

故障排查

现象	原因	修复方式
401 签名不匹配	签名字符串与服务端预期不同	检查换行格式、请求头小写形式，以及第一行为 key_id
401 时钟偏移	Date 请求头与服务端时间差距过大	同步时钟或增大 clock_skew
401 算法不允许	客户端使用的算法不在 allowed_algorithms 中	将算法加入允许列表，或修改客户端
401 请求体摘要不匹配	计算摘要后请求体发生变化	根据实际请求体重新计算 Digest 请求头
签名难以调试	签名字符串较复杂	在客户端记录精确签名字符串并进行比较

配置同步示例

version: "1"
gateway_groups:
  - name: default
    consumers:
      - username: alice
    routes:
      - id: hmac-protected
        uri: /api/*
        plugins:
          hmac-auth: {}
        upstream:
          type: roundrobin
          nodes:
            - host: backend
              port: 8080
              weight: 1

注意：消费者凭证（key_id/secret_key）必须通过 Admin API 单独创建和管理；a7 config sync 会管理消费者资源，但凭证属于子资源。

---

本页面由 api7/a7 仓库中的 a7-plugin-hmac-auth/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。