From bf1d6b1881ad53fb9f3ef3b8967f435169ab99c1 Mon Sep 17 00:00:00 2001 From: Varidhi61 Date: Fri, 9 Jan 2026 22:09:22 +0530 Subject: [PATCH 1/6] docs: add realm description to zh basic-auth route attributes Add 'realm' parameter to basic-auth plugin documentation. --- docs/zh/latest/plugins/basic-auth.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/zh/latest/plugins/basic-auth.md b/docs/zh/latest/plugins/basic-auth.md index c445e45f3dca..49c5aa7dd90d 100644 --- a/docs/zh/latest/plugins/basic-auth.md +++ b/docs/zh/latest/plugins/basic-auth.md @@ -55,6 +55,7 @@ Route 端： | ---------------- | ------- | ------ | ------ | --------------------------------------------------------------- | | hide_credentials | boolean | 否 | false | 该参数设置为 `true` 时，则不会将 Authorization 请求头传递给 Upstream。| | anonymous_consumer | boolean | 否 | false | 匿名消费者名称。如果已配置，则允许匿名用户绕过身份验证。 | +| realm | string | 否 | basic |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| ## 示例 From 7d7cf0e6784d712d6d8ee3b487c84199f5b5d093 Mon Sep 17 00:00:00 2001 From: Vidhi Kashyap Date: Thu, 15 Jan 2026 13:00:41 +0530 Subject: [PATCH 2/6] docs: add realm description to zh auth plugin docs --- docs/zh/latest/plugins/hmac-auth.md | 2 +- docs/zh/latest/plugins/jwt-auth.md | 2 +- docs/zh/latest/plugins/key-auth.md | 2 +- docs/zh/latest/plugins/ldap-auth.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/zh/latest/plugins/hmac-auth.md b/docs/zh/latest/plugins/hmac-auth.md index c4460473980f..c432f0198cc8 100644 --- a/docs/zh/latest/plugins/hmac-auth.md +++ b/docs/zh/latest/plugins/hmac-auth.md @@ -57,7 +57,7 @@ description: hmac-auth 插件支持 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 标头中的域。| 注意：schema 中还定义了 `encrypt_fields = {"secret_key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。 ## 示例 diff --git a/docs/zh/latest/plugins/jwt-auth.md b/docs/zh/latest/plugins/jwt-auth.md index 878cf68fc642..63c425e37a49 100644 --- a/docs/zh/latest/plugins/jwt-auth.md +++ b/docs/zh/latest/plugins/jwt-auth.md @@ -64,7 +64,7 @@ Route 端： | key_claim_name | string | 否 | key | 包含用户密钥（对应消费者的密钥属性）的 JWT 声明的名称。| | anonymous_consumer | string | 否 | false | 匿名消费者名称。如果已配置，则允许匿名用户绕过身份验证。 | | store_in_ctx | boolean | 否 | false | 设置为 `true` 将会将 JWT 负载存储在请求上下文 (`ctx.jwt_auth_payload`) 中。这允许在同一请求上随后运行的低优先级插件检索和使用 JWT 令牌。 | - +| realm | string | 否 | jwt |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| 您可以使用 [HashiCorp Vault](https://www.vaultproject.io/) 实施 `jwt-auth`，以从其[加密的 KV 引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 使用 [APISIX Secret](../terminology/secret.md) 资源。 ## 示例 diff --git a/docs/zh/latest/plugins/key-auth.md b/docs/zh/latest/plugins/key-auth.md index fa6f469fbd7e..03157fe410f8 100644 --- a/docs/zh/latest/plugins/key-auth.md +++ b/docs/zh/latest/plugins/key-auth.md @@ -57,7 +57,7 @@ Route 端： | header | string | 否 | apikey | 设置我们从哪个 header 获取 key。 | | query | string | 否 | apikey | 设置我们从哪个 query string 获取 key，优先级低于 `header`。 | | hide_credentials | boolean | 否 | false | 如果为 `true`，则不要将含有认证信息的 header 或 query string 传递给 Upstream。 | - +| realm | string | 否 | key |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| ## 示例 以下示例演示了如何在不同场景中使用 `key-auth` 插件。 diff --git a/docs/zh/latest/plugins/ldap-auth.md b/docs/zh/latest/plugins/ldap-auth.md index 0417879fd12a..e9cd013ff71f 100644 --- a/docs/zh/latest/plugins/ldap-auth.md +++ b/docs/zh/latest/plugins/ldap-auth.md @@ -51,7 +51,7 @@ Route 端： | use_tls | boolean | 否 | false | 如果设置为 `true` 则表示启用 TLS。 | | tls_verify| boolean | 否 | false | 是否校验 LDAP 服务器的证书。如果设置为 `true`，你必须设置 `config.yaml` 里面的 `ssl_trusted_certificate`，并且确保 `ldap_uri` 里的 host 和服务器证书中的 host 匹配。 | | uid | string | 否 | cn | UID 属性。 | - +| realm | string | 否 | ldap |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| ## 启用插件 首先，你需要创建一个 Consumer 并在其中配置该插件，具体代码如下： From b16aee7036b531c476812faf81d29a6a7657f4dc Mon Sep 17 00:00:00 2001 From: Vidhi Kashyap Date: Thu, 15 Jan 2026 13:31:38 +0530 Subject: [PATCH 3/6] docs: fix markdown heading spacing in zh auth plugin docs --- docs/zh/latest/plugins/key-auth.md | 1 + docs/zh/latest/plugins/ldap-auth.md | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/zh/latest/plugins/key-auth.md b/docs/zh/latest/plugins/key-auth.md index 03157fe410f8..fbb42ce0f944 100644 --- a/docs/zh/latest/plugins/key-auth.md +++ b/docs/zh/latest/plugins/key-auth.md @@ -58,6 +58,7 @@ Route 端： | query | string | 否 | apikey | 设置我们从哪个 query string 获取 key，优先级低于 `header`。 | | hide_credentials | boolean | 否 | false | 如果为 `true`，则不要将含有认证信息的 header 或 query string 传递给 Upstream。 | | realm | string | 否 | key |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| + ## 示例 以下示例演示了如何在不同场景中使用 `key-auth` 插件。 diff --git a/docs/zh/latest/plugins/ldap-auth.md b/docs/zh/latest/plugins/ldap-auth.md index e9cd013ff71f..9a5ab5a429c5 100644 --- a/docs/zh/latest/plugins/ldap-auth.md +++ b/docs/zh/latest/plugins/ldap-auth.md @@ -52,6 +52,7 @@ Route 端： | tls_verify| boolean | 否 | false | 是否校验 LDAP 服务器的证书。如果设置为 `true`，你必须设置 `config.yaml` 里面的 `ssl_trusted_certificate`，并且确保 `ldap_uri` 里的 host 和服务器证书中的 host 匹配。 | | uid | string | 否 | cn | UID 属性。 | | realm | string | 否 | ldap |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| + ## 启用插件 首先，你需要创建一个 Consumer 并在其中配置该插件，具体代码如下： From 1ee9d75db01fa01ffd8a80de88c3bd8312e79e89 Mon Sep 17 00:00:00 2001 From: Traky Deng Date: Thu, 15 Jan 2026 16:11:24 +0800 Subject: [PATCH 4/6] Apply suggestions from review --- docs/zh/latest/plugins/basic-auth.md | 2 +- docs/zh/latest/plugins/hmac-auth.md | 2 +- docs/zh/latest/plugins/jwt-auth.md | 2 +- docs/zh/latest/plugins/key-auth.md | 2 +- docs/zh/latest/plugins/ldap-auth.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/zh/latest/plugins/basic-auth.md b/docs/zh/latest/plugins/basic-auth.md index 49c5aa7dd90d..f7a70b76c0ce 100644 --- a/docs/zh/latest/plugins/basic-auth.md +++ b/docs/zh/latest/plugins/basic-auth.md @@ -55,7 +55,7 @@ Route 端： | ---------------- | ------- | ------ | ------ | --------------------------------------------------------------- | | hide_credentials | boolean | 否 | false | 该参数设置为 `true` 时，则不会将 Authorization 请求头传递给 Upstream。| | anonymous_consumer | boolean | 否 | false | 匿名消费者名称。如果已配置，则允许匿名用户绕过身份验证。 | -| realm | string | 否 | basic |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| +| realm | string | 否 | basic |在身份验证失败时，应包含在 `WWW-Authenticate` 标头中的域。| ## 示例 diff --git a/docs/zh/latest/plugins/hmac-auth.md b/docs/zh/latest/plugins/hmac-auth.md index c432f0198cc8..536908a7d0ce 100644 --- a/docs/zh/latest/plugins/hmac-auth.md +++ b/docs/zh/latest/plugins/hmac-auth.md @@ -57,7 +57,7 @@ description: hmac-auth 插件支持 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 标头中的域。| +| realm | string | 否 | hmac |在身份验证失败时，应包含在 `WWW-Authenticate` 标头中的域。| 注意：schema 中还定义了 `encrypt_fields = {"secret_key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。 ## 示例 diff --git a/docs/zh/latest/plugins/jwt-auth.md b/docs/zh/latest/plugins/jwt-auth.md index 63c425e37a49..e5b26ab0dc54 100644 --- a/docs/zh/latest/plugins/jwt-auth.md +++ b/docs/zh/latest/plugins/jwt-auth.md @@ -64,7 +64,7 @@ Route 端： | key_claim_name | string | 否 | key | 包含用户密钥（对应消费者的密钥属性）的 JWT 声明的名称。| | anonymous_consumer | string | 否 | false | 匿名消费者名称。如果已配置，则允许匿名用户绕过身份验证。 | | store_in_ctx | boolean | 否 | false | 设置为 `true` 将会将 JWT 负载存储在请求上下文 (`ctx.jwt_auth_payload`) 中。这允许在同一请求上随后运行的低优先级插件检索和使用 JWT 令牌。 | -| realm | string | 否 | jwt |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| +| realm | string | 否 | jwt |在身份验证失败时，应包含在 `WWW-Authenticate` 标头中的域。| 您可以使用 [HashiCorp Vault](https://www.vaultproject.io/) 实施 `jwt-auth`，以从其[加密的 KV 引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 使用 [APISIX Secret](../terminology/secret.md) 资源。 ## 示例 diff --git a/docs/zh/latest/plugins/key-auth.md b/docs/zh/latest/plugins/key-auth.md index fbb42ce0f944..08e2ac1646bf 100644 --- a/docs/zh/latest/plugins/key-auth.md +++ b/docs/zh/latest/plugins/key-auth.md @@ -57,7 +57,7 @@ Route 端： | header | string | 否 | apikey | 设置我们从哪个 header 获取 key。 | | query | string | 否 | apikey | 设置我们从哪个 query string 获取 key，优先级低于 `header`。 | | hide_credentials | boolean | 否 | false | 如果为 `true`，则不要将含有认证信息的 header 或 query string 传递给 Upstream。 | -| realm | string | 否 | key |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| +| realm | string | 否 | key |在身份验证失败时，应包含在 `WWW-Authenticate` 标头中的域。| ## 示例 diff --git a/docs/zh/latest/plugins/ldap-auth.md b/docs/zh/latest/plugins/ldap-auth.md index 9a5ab5a429c5..5ecd0b83ae84 100644 --- a/docs/zh/latest/plugins/ldap-auth.md +++ b/docs/zh/latest/plugins/ldap-auth.md @@ -51,7 +51,7 @@ Route 端： | use_tls | boolean | 否 | false | 如果设置为 `true` 则表示启用 TLS。 | | tls_verify| boolean | 否 | false | 是否校验 LDAP 服务器的证书。如果设置为 `true`，你必须设置 `config.yaml` 里面的 `ssl_trusted_certificate`，并且确保 `ldap_uri` 里的 host 和服务器证书中的 host 匹配。 | | uid | string | 否 | cn | UID 属性。 | -| realm | string | 否 | ldap |在身份验证失败时，应包含在 WWW-Authenticate 标头中的域。| +| realm | string | 否 | ldap |在身份验证失败时，应包含在 `WWW-Authenticate` 标头中的域。| ## 启用插件 From 530be8ba273da4472bd4c716131492f9ffb00659 Mon Sep 17 00:00:00 2001 From: Vidhi Kashyap Date: Wed, 21 Jan 2026 14:18:28 +0530 Subject: [PATCH 5/6] docs(zh): apply review suggestions for auth plugin docs --- docs/zh/latest/plugins/hmac-auth.md | 2 ++ docs/zh/latest/plugins/jwt-auth.md | 1 + 2 files changed, 3 insertions(+) diff --git a/docs/zh/latest/plugins/hmac-auth.md b/docs/zh/latest/plugins/hmac-auth.md index 536908a7d0ce..50a4e4dfd4b0 100644 --- a/docs/zh/latest/plugins/hmac-auth.md +++ b/docs/zh/latest/plugins/hmac-auth.md @@ -58,6 +58,8 @@ description: hmac-auth 插件支持 HMAC 认证，保证请求的完整性，防 | hide_credentials | boolean | 否 | false | | 如果为 true，则不会将授权请求头传递给上游服务。 | | anonymous_consumer | string | 否 | | | 匿名消费者名称。如果已配置，则允许匿名用户绕过身份验证。 | | realm | string | 否 | hmac |在身份验证失败时，应包含在 `WWW-Authenticate` 标头中的域。| + + 注意：schema 中还定义了 `encrypt_fields = {"secret_key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。 ## 示例 diff --git a/docs/zh/latest/plugins/jwt-auth.md b/docs/zh/latest/plugins/jwt-auth.md index e5b26ab0dc54..84dfcb8d4620 100644 --- a/docs/zh/latest/plugins/jwt-auth.md +++ b/docs/zh/latest/plugins/jwt-auth.md @@ -65,6 +65,7 @@ Route 端： | anonymous_consumer | string | 否 | false | 匿名消费者名称。如果已配置，则允许匿名用户绕过身份验证。 | | store_in_ctx | boolean | 否 | false | 设置为 `true` 将会将 JWT 负载存储在请求上下文 (`ctx.jwt_auth_payload`) 中。这允许在同一请求上随后运行的低优先级插件检索和使用 JWT 令牌。 | | realm | string | 否 | jwt |在身份验证失败时，应包含在 `WWW-Authenticate` 标头中的域。| + 您可以使用 [HashiCorp Vault](https://www.vaultproject.io/) 实施 `jwt-auth`，以从其[加密的 KV 引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 使用 [APISIX Secret](../terminology/secret.md) 资源。 ## 示例 From 9190bae8a9a16b48cdf8df1abff094e2654de17b Mon Sep 17 00:00:00 2001 From: Varidhi61 Date: Mon, 26 Jan 2026 19:13:54 +0530 Subject: [PATCH 6/6] docs: fix markdownlint MD012 in hmac-auth doc Removed an empty line before the note about schema encryption. --- docs/zh/latest/plugins/hmac-auth.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/zh/latest/plugins/hmac-auth.md b/docs/zh/latest/plugins/hmac-auth.md index 50a4e4dfd4b0..071b88e46b87 100644 --- a/docs/zh/latest/plugins/hmac-auth.md +++ b/docs/zh/latest/plugins/hmac-auth.md @@ -59,7 +59,6 @@ description: hmac-auth 插件支持 HMAC 认证，保证请求的完整性，防 | anonymous_consumer | string | 否 | | | 匿名消费者名称。如果已配置，则允许匿名用户绕过身份验证。 | | realm | string | 否 | hmac |在身份验证失败时，应包含在 `WWW-Authenticate` 标头中的域。| - 注意：schema 中还定义了 `encrypt_fields = {"secret_key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。 ## 示例