You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by "Yilialinn (via GitHub)" <gi...@apache.org> on 2026/04/17 06:27:26 UTC
[PR] docs(hmac-auth): re-port with Admin API, ADC, and Ingress Controller tabs [apisix]
Yilialinn opened a new pull request, #13242:
URL: https://github.com/apache/apisix/pull/13242
## Summary
Re-ports the `hmac-auth` plugin documentation with the following updates:
- Added canonical link in `<head>` pointing to API7 docs
- Updated Consumer/Credential attribute table to 6-column format with `key_id` field (replacing incorrect `access_key`)
- Added ADC and Ingress Controller (Gateway API + APISIX CRD) tabs to all four examples
- Added separate Implementation section describing how HMAC verification works
- Fixed `X-Credential-Identifier` header name typo (`Indentifier` → `Identifier`)
- Updated admin_key retrieval path to `/usr/local/apisix/conf/config.yaml`
- Removed highlight annotations and enterprise-only content
- Updated Chinese translation with full tab structure and fixed field names
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs(hmac-auth): re-port with Admin API, ADC, and Ingress Controller tabs [apisix]
Posted by "kayx23 (via GitHub)" <gi...@apache.org>.
kayx23 commented on code in PR #13242:
URL: https://github.com/apache/apisix/pull/13242#discussion_r3109768693
##########
docs/en/latest/plugins/hmac-auth.md:
##########
Review Comment:
In the anonymous-consumer rate-limit example, the route is configured on `/get`, but the verification requests near the end use `/anything`. As written, those requests will miss the configured route, so the expected `200`/`429` result here will not match unless the request path is updated to `/get` (or the route is changed to `/anything`).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs(hmac-auth): re-port with Admin API, ADC, and Ingress Controller tabs [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn merged PR #13242:
URL: https://github.com/apache/apisix/pull/13242
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs(hmac-auth): re-port with Admin API, ADC, and Ingress Controller tabs [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn commented on code in PR #13242:
URL: https://github.com/apache/apisix/pull/13242#discussion_r3116609800
##########
docs/en/latest/plugins/hmac-auth.md:
##########
Review Comment:
Fixed. Both verification requests (the authenticated `john` request and the anonymous request) now use `/get` to match the configured route URI. Note the HMAC signature was already computed for `/get` (the Python script uses `request_path = "/get"`), so only the curl URLs needed updating. Same fix applied to the ZH doc.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs(hmac-auth): re-port with Admin API, ADC, and Ingress Controller tabs [apisix]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13242:
URL: https://github.com/apache/apisix/pull/13242#discussion_r3099163501
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -28,58 +28,78 @@ description: hmac-auth 插件支持 HMAC 认证,保证请求的完整性,防
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/hmac-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
`hmac-auth` 插件支持 HMAC(基于哈希的消息认证码)认证,作为一种确保请求完整性的机制,防止它们在传输过程中被修改。要使用该插件,您需要在 [Consumers](../terminology/consumer.md) 上配置 HMAC 密钥,并在 Routes 或 Services 上启用该插件。
-当消费者成功通过身份验证后,APISIX 会在将请求代理到上游服务之前向请求添加其他标头,例如 `X-Consumer-Username`、`X-Credential-Indentifier` 和其他消费者自定义标头(如果已配置)。上游服务将能够区分消费者并根据需要实现其他逻辑。如果这些值中的任何一个不可用,则不会添加相应的标头。
+当 Consumer 成功通过身份验证后,APISIX 会在将请求代理到上游服务之前向请求添加其他标头,例如 `X-Consumer-Username`、`X-Credential-Identifier` 和其他 Consumer 自定义标头(如果已配置)。上游服务将能够区分 Consumer 并根据需要实现其他逻辑。如果这些值中的任何一个不可用,则不会添加相应的标头。
+
+## 实现原理
-启用后,插件会验证请求的 `Authorization` 标头中的 HMAC 签名,并检查传入的请求是否来自受信任的来源。具体来说,当 APISIX 收到 HMAC 签名的请求时,会从 `Authorization` 标头中提取密钥 ID。然后,APISIX 会检索相应的消费者配置,包括密钥。如果密钥 ID 有效且存在,APISIX 将使用请求的 `Date` 标头和密钥生成 HMAC 签名。如果生成的签名与 `Authorization` 标头中提供的签名匹配,则请求通过身份验证并转发到上游服务。
+启用后,插件会验证请求的 `Authorization` 标头中的 HMAC 签名,并检查传入的请求是否来自受信任的来源。具体来说,当 APISIX 收到 HMAC 签名的请求时,会从 `Authorization` 标头中提取密钥 ID。然后,APISIX 会检索相应的 Consumer 配置,包括密钥。如果密钥 ID 有效且存在,APISIX 将使用请求的 `Date` 标头和密钥生成 HMAC 签名。如果生成的签名与 `Authorization` 标头中提供的签名匹配,则请求通过身份验证并转发到上游服务。
插件实现基于 [draft-cavage-http-signatures](https://www.ietf.org/archive/id/draft-cavage-http-signatures-12.txt)。
## 属性
以下属性可用于 Consumers 或 Credentials 的配置。
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------- | ------------- | ------ | ------------- | ------------------------------------------| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| access_key | string | 是 | | | 消费者的唯一标识符,用于标识相关配置,例如密钥。 |
-| secret_key | string | 是 | | | 用于生成 HMAC 的密钥。此字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------------|--------|--------|--------|--------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| key_id | string | 是 | | | Consumer 的唯一标识符,用于标识相关配置,例如密钥。 |
+| secret_key | string | 是 | | | 用于生成 HMAC 的密钥。此字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
-以下属性可用于 Routes 或 Services 的配置。
+注意:schema 中还定义了 `encrypt_fields = {"secret_key"}`,这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------- | ------------- | ------ | ------------- | ------------------------------------------| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| allowed_algorithms | array[string] | 否 | ["hmac-sha1", "hmac-sha256", "hmac-sha512"] | "hmac-sha1"、"hmac-sha256" 和 "hmac-sha512" 的组合 | 允许的 HMAC 算法列表。 |
-| clock_skew | integer | 否 | 300 | >=1 | 客户端请求的时间戳与 APISIX 服务器当前时间之间允许的最大时间差(以秒为单位)。这有助于解决客户端和服务器之间的时间同步差异,并防止重放攻击。时间戳将根据 Date 头中的时间(必须为 GMT 格式)进行计算。 |
-| signed_headers | array[string] | 否 | | | 客户端请求的 HMAC 签名中应包含的 HMAC 签名头列表。 |
-| validate_request_body | boolean | 否 | false | | 如果为 true,则验证请求正文的完整性,以确保在传输过程中没有被篡改。具体来说,插件会创建一个 SHA-256 的 base64 编码 digest,并将其与 `Digest` 头进行比较。如果 `Digest` 头丢失或 digest 不匹配,验证将失败。 |
-| hide_credentials | boolean | 否 | false | | 如果为 true,则不会将授权请求头传递给上游服务。 |
-| anonymous_consumer | string | 否 | | | 匿名消费者名称。如果已配置,则允许匿名用户绕过身份验证。 |
-| realm | string | 否 | hmac |在身份验证失败时,应包含在 `WWW-Authenticate` 标头中的域。|
+以下属性可用于 Routes 或 Services 的配置。
-注意:schema 中还定义了 `encrypt_fields = {"secret_key"}`,这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|-----------------------|---------------|--------|------------------------------------------------|---------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| allowed_algorithms | array[string] | 否 | `["hmac-sha1", "hmac-sha256", "hmac-sha512"]` | `"hmac-sha1"`、`"hmac-sha256"` 和 `"hmac-sha512"` 的组合 | 允许的 HMAC 算法列表。 |
+| clock_skew | integer | 否 | 300 | >=1 | 客户端请求的时间戳与 APISIX 服务器当前时间之间允许的最大时间差(以秒为单位)。这有助于解决客户端和服务器之间的时间同步差异,并防止重放攻击。时间戳将根据 `Date` 头中的时间(必须为 GMT 格式)进行计算。 |
+| signed_headers | array[string] | 否 | | | 客户端请求的 HMAC 签名中应包含的标头列表。 |
+| validate_request_body | boolean | 否 | false | | 如果为 true,则验证请求正文的完整性,以确保在传输过程中没有被篡改。具体来说,插件会创建一个 SHA-256 的 base64 编码 digest,并将其与 `Digest` 头进行比较。如果 `Digest` 头丢失或 digest 不匹配,验证将失败。 |
+| hide_credentials | boolean | 否 | false | | 如果为 true,则不会将授权请求头传递给上游服务。 |
+| anonymous_consumer | string | 否 | | | 匿名 Consumer 名称。如果已配置,则允许匿名用户绕过身份验证。 |
+| realm | string | 否 | `hmac` | | 在身份验证失败时,[`WWW-Authenticate`](https://datatracker.ietf.org/doc/html/rfc7235#section-4.1) 响应标头中返回的域,状态码为 `401 Unauthorized`。 |
## 示例
-下面的示例说明了如何在不同场景中使用“hmac-auth”插件。
+下面的示例说明了如何在不同场景中使用 `hmac-auth` 插件。
:::note
您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量:
```bash
-admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+admin_key=$(yq '.deployment.admin.admin_key[0].key' /usr/local/apisix/conf/config.yaml | sed 's/"//g')
Review Comment:
这里说明“从 `config.yaml` 获取 admin_key”,但命令固定使用 `/usr/local/apisix/conf/config.yaml`。仓库中大多数文档示例使用 `conf/config.yaml`。建议保持一致,或同时说明不同安装方式(源码/包/Docker)对应的路径,避免读者照抄失败。
##########
docs/en/latest/plugins/hmac-auth.md:
##########
@@ -28,38 +28,47 @@ description: The hmac-auth Plugin supports HMAC authentication to ensure request
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/hmac-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
The `hmac-auth` Plugin supports HMAC (Hash-based Message Authentication Code) authentication as a mechanism to ensure the integrity of requests, preventing them from being modified during transmissions. To use the Plugin, you would configure HMAC secret keys on [Consumers](../terminology/consumer.md) and enable the Plugin on Routes or Services.
-When a Consumer is successfully authenticated, APISIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Indentifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
+When a Consumer is successfully authenticated, APISIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Identifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
+
+## Implementation
-Once enabled, the Plugin verifies the HMAC signature in the request's `Authorization` header and check that incoming requests are from trusted sources. Specifically, when APISIX receives an HMAC-signed request, the key ID is extracted from the `Authorization` header. APISIX then retrieves the corresponding Consumer configuration, including the secret key. If the key ID is valid and exists, APISIX generates an HMAC signature using the request's `Date` header and the secret key. If this generated signature matches the signature provided in the `Authorization` header, the request is authenticated and forwarded to Upstream services.
+Once enabled, the Plugin verifies the HMAC signature in the request's `Authorization` header and checks that incoming requests are from trusted sources. Specifically, when APISIX receives an HMAC-signed request, the key ID is extracted from the `Authorization` header. APISIX then retrieves the corresponding Consumer configuration, including the secret key. If the key ID is valid and exists, APISIX generates an HMAC signature using the request's `Date` header and the secret key. If this generated signature matches the signature provided in the `Authorization` header, the request is authenticated and forwarded to Upstream services.
The Plugin implementation is based on [draft-cavage-http-signatures](https://www.ietf.org/archive/id/draft-cavage-http-signatures-12.txt).
## Attributes
The following attributes are available for configurations on Consumers or Credentials.
-| Name | Type | Required | Default | Valid values | Description |
-|-----------------------|---------------|----------|---------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| key_id | string | True | | | Unique identifier for the Consumer, which identifies the associated configurations such as the secret key. |
-| secret_key | string | True | | | Secret key used to generate an HMAC. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
+| Name | Type | Required | Default | Valid values | Description |
+|------------|--------|----------|---------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| key_id | string | True | | | Unique identifier for the Consumer, which identifies the associated configurations such as the secret key. |
Review Comment:
`key_id` is the HMAC credential key identifier used as `keyId` in the Signature Authorization header (and used to look up the matching Consumer/Credential). Calling it the “Unique identifier for the Consumer” is misleading, since the Consumer itself is identified by `username` while `key_id` identifies the HMAC key/credential.
```suggestion
| key_id | string | True | | | Unique identifier for the HMAC credential/key, used as `keyId` in the Signature `Authorization` header to identify the associated credential configuration such as the secret key. |
```
##########
docs/en/latest/plugins/hmac-auth.md:
##########
@@ -28,38 +28,47 @@ description: The hmac-auth Plugin supports HMAC authentication to ensure request
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/hmac-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
The `hmac-auth` Plugin supports HMAC (Hash-based Message Authentication Code) authentication as a mechanism to ensure the integrity of requests, preventing them from being modified during transmissions. To use the Plugin, you would configure HMAC secret keys on [Consumers](../terminology/consumer.md) and enable the Plugin on Routes or Services.
-When a Consumer is successfully authenticated, APISIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Indentifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
+When a Consumer is successfully authenticated, APISIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Identifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
Review Comment:
Grammar: “implement additional logics” should be “implement additional logic”.
```suggestion
When a Consumer is successfully authenticated, APISIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Identifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logic as needed. If any of these values is not available, the corresponding header will not be added.
```
##########
docs/en/latest/plugins/hmac-auth.md:
##########
@@ -70,14 +79,25 @@ The examples below demonstrate how you can work with the `hmac-auth` Plugin for
You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
```bash
-admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+admin_key=$(yq '.deployment.admin.admin_key[0].key' /usr/local/apisix/conf/config.yaml | sed 's/"//g')
```
:::
### Implement HMAC Authentication on a Route
-The following example demonstrates how to implement HMAC authentications on a route. You will also attach a Consumer custom ID to authenticated request in the `Consumer-Custom-Id` header, which can be used to implement additional logics as needed.
+The following example demonstrates how to implement HMAC authentication on a Route. You will also attach a Consumer custom ID to authenticated requests in the `X-Consumer-Custom-Id` header, which can be used to implement additional logics as needed.
Review Comment:
Grammar: “implement additional logics” should be “implement additional logic”.
```suggestion
The following example demonstrates how to implement HMAC authentication on a Route. You will also attach a Consumer custom ID to authenticated requests in the `X-Consumer-Custom-Id` header, which can be used to implement additional logic as needed.
```
##########
docs/en/latest/plugins/hmac-auth.md:
##########
@@ -70,14 +79,25 @@ The examples below demonstrate how you can work with the `hmac-auth` Plugin for
You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
```bash
-admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+admin_key=$(yq '.deployment.admin.admin_key[0].key' /usr/local/apisix/conf/config.yaml | sed 's/"//g')
Review Comment:
This note says to fetch `admin_key` from `config.yaml`, but the command hard-codes `/usr/local/apisix/conf/config.yaml`. Most other docs in this repo use `conf/config.yaml` (relative to the APISIX install/source tree). Consider either keeping `conf/config.yaml` for consistency or documenting both paths (e.g., source install vs Docker image) to avoid confusing readers.
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -28,58 +28,78 @@ description: hmac-auth 插件支持 HMAC 认证,保证请求的完整性,防
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/hmac-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
`hmac-auth` 插件支持 HMAC(基于哈希的消息认证码)认证,作为一种确保请求完整性的机制,防止它们在传输过程中被修改。要使用该插件,您需要在 [Consumers](../terminology/consumer.md) 上配置 HMAC 密钥,并在 Routes 或 Services 上启用该插件。
-当消费者成功通过身份验证后,APISIX 会在将请求代理到上游服务之前向请求添加其他标头,例如 `X-Consumer-Username`、`X-Credential-Indentifier` 和其他消费者自定义标头(如果已配置)。上游服务将能够区分消费者并根据需要实现其他逻辑。如果这些值中的任何一个不可用,则不会添加相应的标头。
+当 Consumer 成功通过身份验证后,APISIX 会在将请求代理到上游服务之前向请求添加其他标头,例如 `X-Consumer-Username`、`X-Credential-Identifier` 和其他 Consumer 自定义标头(如果已配置)。上游服务将能够区分 Consumer 并根据需要实现其他逻辑。如果这些值中的任何一个不可用,则不会添加相应的标头。
+
+## 实现原理
-启用后,插件会验证请求的 `Authorization` 标头中的 HMAC 签名,并检查传入的请求是否来自受信任的来源。具体来说,当 APISIX 收到 HMAC 签名的请求时,会从 `Authorization` 标头中提取密钥 ID。然后,APISIX 会检索相应的消费者配置,包括密钥。如果密钥 ID 有效且存在,APISIX 将使用请求的 `Date` 标头和密钥生成 HMAC 签名。如果生成的签名与 `Authorization` 标头中提供的签名匹配,则请求通过身份验证并转发到上游服务。
+启用后,插件会验证请求的 `Authorization` 标头中的 HMAC 签名,并检查传入的请求是否来自受信任的来源。具体来说,当 APISIX 收到 HMAC 签名的请求时,会从 `Authorization` 标头中提取密钥 ID。然后,APISIX 会检索相应的 Consumer 配置,包括密钥。如果密钥 ID 有效且存在,APISIX 将使用请求的 `Date` 标头和密钥生成 HMAC 签名。如果生成的签名与 `Authorization` 标头中提供的签名匹配,则请求通过身份验证并转发到上游服务。
插件实现基于 [draft-cavage-http-signatures](https://www.ietf.org/archive/id/draft-cavage-http-signatures-12.txt)。
## 属性
以下属性可用于 Consumers 或 Credentials 的配置。
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------- | ------------- | ------ | ------------- | ------------------------------------------| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| access_key | string | 是 | | | 消费者的唯一标识符,用于标识相关配置,例如密钥。 |
-| secret_key | string | 是 | | | 用于生成 HMAC 的密钥。此字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------------|--------|--------|--------|--------|------------------------------------------------------------------------------------------------------------------------------------------------|
+| key_id | string | 是 | | | Consumer 的唯一标识符,用于标识相关配置,例如密钥。 |
Review Comment:
表格中将 `key_id` 描述为“Consumer 的唯一标识符”容易误解。`key_id` 实际是 HMAC Credential 的 key 标识(对应 `Authorization` 里的 `keyId`,并用于查找匹配的 Consumer/Credential),而 Consumer 本身通常由 `username` 标识。建议把描述改为“用于标识 HMAC 密钥/凭证的 keyId”等更准确的说法。
```suggestion
| key_id | string | 是 | | | 用于标识 HMAC 密钥/凭证的 keyId,并用于查找关联的 Consumer/Credential。 |
```
##########
docs/zh/latest/plugins/hmac-auth.md:
##########
@@ -28,58 +28,78 @@ description: hmac-auth 插件支持 HMAC 认证,保证请求的完整性,防
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/hmac-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
`hmac-auth` 插件支持 HMAC(基于哈希的消息认证码)认证,作为一种确保请求完整性的机制,防止它们在传输过程中被修改。要使用该插件,您需要在 [Consumers](../terminology/consumer.md) 上配置 HMAC 密钥,并在 Routes 或 Services 上启用该插件。
-当消费者成功通过身份验证后,APISIX 会在将请求代理到上游服务之前向请求添加其他标头,例如 `X-Consumer-Username`、`X-Credential-Indentifier` 和其他消费者自定义标头(如果已配置)。上游服务将能够区分消费者并根据需要实现其他逻辑。如果这些值中的任何一个不可用,则不会添加相应的标头。
+当 Consumer 成功通过身份验证后,APISIX 会在将请求代理到上游服务之前向请求添加其他标头,例如 `X-Consumer-Username`、`X-Credential-Identifier` 和其他 Consumer 自定义标头(如果已配置)。上游服务将能够区分 Consumer 并根据需要实现其他逻辑。如果这些值中的任何一个不可用,则不会添加相应的标头。
+
+## 实现原理
-启用后,插件会验证请求的 `Authorization` 标头中的 HMAC 签名,并检查传入的请求是否来自受信任的来源。具体来说,当 APISIX 收到 HMAC 签名的请求时,会从 `Authorization` 标头中提取密钥 ID。然后,APISIX 会检索相应的消费者配置,包括密钥。如果密钥 ID 有效且存在,APISIX 将使用请求的 `Date` 标头和密钥生成 HMAC 签名。如果生成的签名与 `Authorization` 标头中提供的签名匹配,则请求通过身份验证并转发到上游服务。
+启用后,插件会验证请求的 `Authorization` 标头中的 HMAC 签名,并检查传入的请求是否来自受信任的来源。具体来说,当 APISIX 收到 HMAC 签名的请求时,会从 `Authorization` 标头中提取密钥 ID。然后,APISIX 会检索相应的 Consumer 配置,包括密钥。如果密钥 ID 有效且存在,APISIX 将使用请求的 `Date` 标头和密钥生成 HMAC 签名。如果生成的签名与 `Authorization` 标头中提供的签名匹配,则请求通过身份验证并转发到上游服务。
Review Comment:
“实现原理”部分对签名校验流程描述不准确:插件会从 `Authorization: Signature ...` 中解析 `keyId/algorithm/signature/headers`,按 `headers` 列表(含 `@request-target` 以及被签名的标头)拼接 signing string,生成 HMAC 后与 base64 解码后的 `signature` 比较;`Date` 主要用于 clock skew 校验(只有当其出现在 `headers` 列表中时才参与签名)。建议按实际实现补充/修正。
```suggestion
启用后,插件会验证请求 `Authorization: Signature ...` 中携带的签名,以确认请求内容未被篡改且来自持有对应密钥的调用方。具体来说,APISIX 会先从 `Authorization` 标头中解析 `keyId`、`algorithm`、`signature` 和 `headers` 等参数,再根据 `keyId` 查找对应的 Consumer 或 Credential 配置并获取密钥。随后,插件会按照 `headers` 列表中声明的顺序拼接 signing string,其中可包含 `@request-target` 以及其他参与签名的请求标头,然后使用指定算法和密钥生成 HMAC,并将结果与 `signature` 参数经 base64 解码后的值进行比较。只有两者一致时,请求才会通过身份验证并转发到上游服务。
`Date` 标头主要用于 clock skew(时钟偏移)校验;只有当它被显式包含在 `headers` 列表中时,才会作为 signing string 的一部分参与签名计算。
```
##########
docs/en/latest/plugins/hmac-auth.md:
##########
@@ -28,38 +28,47 @@ description: The hmac-auth Plugin supports HMAC authentication to ensure request
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/hmac-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
The `hmac-auth` Plugin supports HMAC (Hash-based Message Authentication Code) authentication as a mechanism to ensure the integrity of requests, preventing them from being modified during transmissions. To use the Plugin, you would configure HMAC secret keys on [Consumers](../terminology/consumer.md) and enable the Plugin on Routes or Services.
-When a Consumer is successfully authenticated, APISIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Indentifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
+When a Consumer is successfully authenticated, APISIX adds additional headers, such as `X-Consumer-Username`, `X-Credential-Identifier`, and other Consumer custom headers if configured, to the request, before proxying it to the Upstream service. The Upstream service will be able to differentiate between consumers and implement additional logics as needed. If any of these values is not available, the corresponding header will not be added.
+
+## Implementation
-Once enabled, the Plugin verifies the HMAC signature in the request's `Authorization` header and check that incoming requests are from trusted sources. Specifically, when APISIX receives an HMAC-signed request, the key ID is extracted from the `Authorization` header. APISIX then retrieves the corresponding Consumer configuration, including the secret key. If the key ID is valid and exists, APISIX generates an HMAC signature using the request's `Date` header and the secret key. If this generated signature matches the signature provided in the `Authorization` header, the request is authenticated and forwarded to Upstream services.
+Once enabled, the Plugin verifies the HMAC signature in the request's `Authorization` header and checks that incoming requests are from trusted sources. Specifically, when APISIX receives an HMAC-signed request, the key ID is extracted from the `Authorization` header. APISIX then retrieves the corresponding Consumer configuration, including the secret key. If the key ID is valid and exists, APISIX generates an HMAC signature using the request's `Date` header and the secret key. If this generated signature matches the signature provided in the `Authorization` header, the request is authenticated and forwarded to Upstream services.
Review Comment:
The Implementation description oversimplifies signature verification: the plugin builds a signing string from `keyId` and the `headers` list in the `Authorization: Signature ...` value (including `@request-target` and any signed headers) and compares the base64-decoded `signature` against the generated HMAC. The `Date` header is primarily used for clock-skew validation (and is only part of the signature if included in the `headers` list). Please adjust this section to match the actual verification flow.
```suggestion
Once enabled, the Plugin verifies the HMAC signature in the request's `Authorization` header to confirm that incoming requests are from trusted sources. Specifically, when APISIX receives an HMAC-signed request, it parses the `Authorization: Signature ...` value, extracts the `keyId`, the list of signed `headers`, and the `signature`, and then retrieves the corresponding Consumer configuration, including the secret key. If the `keyId` is valid and exists, APISIX rebuilds the signing string from the declared `headers` list in the order provided, including special entries such as `@request-target` and any signed request headers, and generates an HMAC from that signing string with the secret key. APISIX then base64-decodes the signature from the `Authorization` header and compares it with the generated HMAC. The `Date` header is used primarily for clock-skew validation, and it is only part of the signature when it is explicitly included in the `headers` list. If the verification succ
eeds, the request is authenticated and forwarded to Upstream services.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org