HMAC Auth Configuration

Configuration reference for the HMAC Auth plugin (`hmac-auth`): the parameters on credentials and routes or services, each attribute with its type, whether it is required, its default and its accepted values.

Parameters

See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.

Credentials

The following are plugin attributes available for configurations on credentials (opens in Apache APISIX docs).

key_id — string · required · since APISIX 3.11.0 · API7 Gateway 3.2.15.0

Unique identifier for the consumer, which identifies the associated configurations such as the secret key.

secret_key — string · required · since APISIX 2.0 · API7 Gateway 3.2.15.0

Secret key used to generate an HMAC.

The key is encrypted with AES before being stored in etcd. You can also store it in an environment variable and reference it using the env:// prefix, or in a secret manager such as HashiCorp Vault's KV secrets engine, and reference it using the secret:// prefix. For more information, see secrets (opens in Apache APISIX docs).

Routes or Services

The following are plugin attributes available for configurations on routes (opens in Apache APISIX docs) or services (opens in Apache APISIX docs).

allowed_algorithms — array[string] · optional · default: ["hmac-sha1", "hmac-sha256", "hmac-sha512"] · since APISIX 3.11.0 · API7 Gateway 3.2.15.0

The list of HMAC algorithms allowed.

clock_skew — integer · optional · default: 300 · since APISIX 3.11.0 · API7 Gateway 3.2.15.0

Valid values: greater than or equal to 1

Maximum allowable time difference in seconds between the client request's timestamp and APISIX server's current time. This helps account for discrepancies in time synchronization between the client’s and server’s clocks and protect against replay attacks. The timestamp in the Date header (must be in GMT format) will be used for the calculation.

signed_headers — array[string] · optional · default: ["date"] · since APISIX 3.11.0 · API7 Gateway 3.2.15.0

The list of headers whose values must be included in the client request's HMAC signature. In API7 Enterprise from version 3.10.0 and APISIX from version 3.17.0, this defaults to ["date"], so the Date header must be signed unless you override this field. If you enable validate_request_body, also include digest so the body digest is covered by the signature.

validate_request_body — boolean · optional · since APISIX 3.11.0 · API7 Gateway 3.2.15.0

If true, compare the request body with the Digest header. The plugin computes a SHA-256 digest of the body, base64-encodes it, and expects Digest to be SHA-256=<digest>. A missing or mismatched Digest header fails validation. This check does not bind the digest to the HMAC signature. Include digest in the signed headers if you want the body digest covered by the signature.

max_req_body_size — integer · optional · default: 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 · since APISIX 3.17.0 · API7 Gateway 3.9.14

Maximum size in bytes of the request body that the plugin reads when validate_request_body is true. A request whose body exceeds this size is rejected (with HTTP 413 in API7 Enterprise from version 3.9.15 and APISIX from version 3.17.0). The default is 524288 bytes (512 KiB) in API7 Enterprise 3.9.14, 3.10.0, and 3.10.1, and 67108864 bytes (64 MiB) in API7 Enterprise from version 3.9.15 and APISIX from version 3.17.0.

hide_credentials — boolean · optional · default: false · since APISIX 3.11.0 · API7 Gateway 3.2.15.0

If true, do not pass the authorization request header to upstream services.

anonymous_consumer — string · optional · since APISIX 3.12.0 · API7 Gateway 3.2.16.3

Anonymous consumer name. If configured, allow anonymous users to bypass the authentication. See Rate Limit with Anonymous Consumer for more details.

realm — string · optional · default: hmac · since APISIX 3.15.0 · API7 Gateway 3.9.2

Realm in the WWW-Authenticate response header returned with a 401 Unauthorized response due to authentication failure. For example:

If realm is set to hmac-auth, the 401 response will include the following header:
```
WWW-Authenticate: hmac realm="hmac-auth"
```
If realm is not configured, the 401 response will include the following header:
```
WWW-Authenticate: hmac realm="hmac"
```

This parameter is available in API7 Enterprise version 3.9.2 and later, and in Apache APISIX version 3.15.0 and later.