# HMAC Auth 配置选项

hmac-auth 插件支持 HMAC 身份认证，以确保请求完整性、防止传输过程中被修改，并增强 API 安全性。<!-- --> <!-- -->配置涵盖凭据字段和路由和服务字段。

## 参数[​](#参数 "参数的直接链接")

请参阅 [插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md) 了解所有插件可用的配置选项。

### 凭据[​](#凭据 "凭据的直接链接")

以下是可在 [凭据](https://docs.apiseven.com/apisix/key-concepts/credentials.md) 上配置的插件属性。

* key\_id

  string

  必填

  ***

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

* secret\_key

  string

  必填

  ***

  用于生成 HMAC 的密钥。

  该密钥在存储到 etcd 之前会使用 AES 加密。你也可以将其存储在环境变量中并使用 `$env://` 前缀引用，或者存储在如 HashiCorp Vault 的 [KV 密钥引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 等密钥管理器中，并使用 `$secret://` 前缀引用。这些网关引用在运行时解析。ADC 的 `${NAME}` 插值有所不同：ADC 在同步前加载配置文件时解析插值。更多信息请参考[密钥](https://docs.apiseven.com/apisix/key-concepts/secrets.md)。

### 路由或服务[​](#路由或服务 "路由或服务的直接链接")

以下是可在 [路由](https://docs.apiseven.com/apisix/key-concepts/routes.md) 或 [服务](https://docs.apiseven.com/apisix/key-concepts/services.md) 上配置的插件属性。

* 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

  ***

  匿名消费者名称。如果配置了此项，允许匿名用户绕过认证。详情请参考 [匿名消费者的速率限制](https://docs.apiseven.com/hub/hmac-auth.md#匿名消费者的速率限制)。

* realm

  string

  默认值：`hmac`

  ***

  身份认证失败时返回的 `401 Unauthorized` 响应中 [`WWW-Authenticate`](https://datatracker.ietf.org/doc/html/rfc7235#section-4.1) 响应头的 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 及更高版本中可用。
