跳到主要内容

参数​

请参阅 插件通用配置 了解所有插件可用的配置选项。

凭据​

以下是可在 凭据 上配置的插件属性。

  • key_id

    string

    必填

    消费者的唯一标识符，用于识别关联的配置，例如密钥。

  • secret_key

    string

    必填

    用于生成 HMAC 的密钥。

    该密钥在存储到 etcd 之前会使用 AES 加密。你也可以将其存储在环境变量中并使用 env:// 前缀引用，或者存储在如 HashiCorp Vault 的 KV 密钥引擎 等密钥管理器中，并使用 secret:// 前缀引用。更多信息请参考密钥。

路由或服务​

以下是可在 路由 或 服务 上配置的插件属性。

  • allowed_algorithms

    array[string]

    默认值：["hmac-sha1", "hmac-sha256", "hmac-sha512"]

    允许的 HMAC 算法列表。

  • clock_skew

    integer

    默认值：300

    有效值：

    大于或等于 1

    允许的客户端请求时间戳与 APISIX 服务器当前时间之间的最大时间差（秒）。这有助于解决客户端与服务器时钟之间的时间同步差异，并防止重放攻击。计算时使用 Date 请求头中的时间戳（必须为 GMT 格式）。

  • signed_headers

    array[string]

    默认值：["date"]

    客户端请求的 HMAC 签名中必须包含的请求头列表。自 API7 企业版 3.10.0 和 APISIX 3.17.0 起，该字段默认值为 ["date"]，因此除非覆盖该字段，否则必须对 Date 请求头签名。如果启用了 validate_request_body，还应包含 digest，以便签名覆盖请求体摘要。

  • validate_request_body

    boolean

    如果为 true，则比较请求体与 Digest 请求头。插件会计算请求体的 SHA-256 摘要并使用 Base64 编码，且要求 Digest 的格式为 SHA-256=<digest>。缺少 Digest 请求头或摘要不匹配时，验证将失败。此检查不会将摘要绑定到 HMAC 签名；如需由签名覆盖请求体摘要，请在签名请求头列表中包含 digest。

  • max_req_body_size

    integer

    默认值：524288 in API7 Enterprise 3.9.14, 3.10.0, and 3.10.1; 67108864 in API7 Enterprise from 3.9.15 and APISIX from 3.17.0

    当 validate_request_body 为 true 时，插件读取的请求体大小上限（字节）。在 API7 企业版 3.9.15 及更高版本和 APISIX 3.17.0 及更高版本中，超过该大小的请求将以 HTTP 413 拒绝。API7 企业版 3.9.14、3.10.0 和 3.10.1 中的默认值为 524288 字节（512 KiB）；API7 企业版 3.9.15 及更高版本和 APISIX 3.17.0 及更高版本中的默认值为 67108864 字节（64 MiB）。

  • hide_credentials

    boolean

    默认值：false

    如果为 true，则不将 authorization 请求头传递给上游服务。

  • anonymous_consumer

    string

    匿名消费者名称。如果配置了此项，允许匿名用户绕过认证。详情请参考 匿名消费者的速率限制。

  • realm

    string

    默认值：hmac

    身份认证失败时返回的 401 Unauthorized 响应中 WWW-Authenticate 响应头的 Realm。例如：

    • 如果 realm 设置为 hmac-auth，401 响应将包含以下响应头：

      WWW-Authenticate: hmac realm="hmac-auth"

    • 如果未配置 realm，401 响应将包含以下响应头：

      WWW-Authenticate: hmac realm="hmac"

    该参数在 API7 企业版版本 3.9.2 及更高版本，以及 Apache APISIX 版本 3.15.0 及更高版本中可用。