HMAC Auth Configuration

Parameters

See plugin common configurations for configuration options available to all plugins.

Credentials

The following are plugin attributes available for configurations on credentials.

• key_id — string · required

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

• secret_key — string · required

  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.

Routes or Services

The following are plugin attributes available for configurations on routes or services.

• allowed_algorithms — array[string] · optional · default: ["hmac-sha1", "hmac-sha256", "hmac-sha512"]

  The list of HMAC algorithms allowed.

• clock_skew — integer · optional · default: 300

  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"]

  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

  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

  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

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

• anonymous_consumer — string · optional

  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

  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.