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 08:46:31 UTC
[PR] docs(jwt-auth): re-port with Admin API, ADC, and Ingress Controller tabs [apisix]
Yilialinn opened a new pull request, #13248:
URL: https://github.com/apache/apisix/pull/13248
Re-ports the jwt-auth plugin documentation with Admin API, ADC, and Ingress Controller tab structure, updated attribute table, and canonical link.
--
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(jwt-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 #13248:
URL: https://github.com/apache/apisix/pull/13248#discussion_r3099162795
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -28,64 +28,81 @@ description: jwt-auth 插件支持使用 JSON Web Token (JWT) 作为客户端在
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/jwt-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`jwt-auth` 插件支持使用 [JSON Web Token (JWT)](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
+`jwt-auth` 插件支持使用 [JSON Web Token（JWT）](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
-启用后，该插件会公开一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自己。该令牌可以包含在请求 URL 查询字符串、请求标头或 cookie 中。然后，APISIX 将验证该令牌以确定是否应允许或拒绝请求访问上游资源。
+启用后，该插件会暴露一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自身。令牌可以包含在请求 URL 查询字符串、请求头或 Cookie 中。APISIX 随后会验证该令牌，以判断是否允许或拒绝请求访问上游资源。
-当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前向请求添加其他标头，例如 `X-Consumer-Username`、`X-Credential-Indentifier` 和其他消费者自定义标头（如已配置）。上游服务将能够区分消费者并根据需要实施其他逻辑。如果任何一个值不可用，则不会添加相应的标题。
+当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前，向请求添加额外的请求头，例如 `X-Consumer-Username`、`X-Credential-Identifier` 以及其他已配置的消费者自定义请求头。上游服务可据此区分消费者并根据需要实现额外逻辑。若某个值不可用，则不会添加对应的请求头。
## 属性
-Consumer/Credential 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------- | ------- | ----- | ------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| key | string | 是 | | | 消费者的唯一密钥。 |
-| secret | string | 否 | | | 当使用对称算法时，用于对 JWT 进行签名和验证的共享密钥。使用 `HS256` 或 `HS512` 作为算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| public_key | string | 否 | | | RSA 或 ECDSA 公钥， `algorithm` 属性选择 `RS256` 或 `ES256` 算法时必选。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| algorithm | string | 否 | "HS256" | ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "EdDSA"] | 加密算法。 |
-| exp | integer | 否 | 86400 | [1,...] | token 的超时时间。 |
-| base64_secret | boolean | 否 | false | | 当设置为 `true` 时，密钥为 base64 编码。 |
-| lifetime_grace_period | integer | 否 | 0 | [0,...] | 宽限期（以秒为单位）。用于解决生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
-| key_claim_name | string | 否 | key | | JWT payload 中的声明用于标识相关的秘密，例如 `iss`。 |
-
-注意：schema 中还定义了 `encrypt_fields = {"secret"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。
-
-Route 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 描述 |
-| ------ | ------ | ------ | ------------- |---------------------------------------------------------|
-| header | string | 否 | authorization | 设置我们从哪个 header 获取 token。 |
-| query | string | 否 | jwt | 设置我们从哪个 query string 获取 token，优先级低于 header。 |
-| cookie | string | 否 | jwt | 设置我们从哪个 cookie 获取 token，优先级低于 query。 |
-| hide_credentials | boolean | 否 | false | 如果为 true，则不要将 header、query 或带有 JWT 的 cookie 传递给上游服务。 |
-| 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` 标头中的域。|
-| claims_to_verify | array[string] | 否 | ["exp", "nbf"] | ["exp", "nbf"] | 需要在 JWT 负载中验证的声明。 |
-
-您可以使用 [HashiCorp Vault](https://www.vaultproject.io/) 实施 `jwt-auth`，以从其[加密的 KV 引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 使用 [APISIX Secret](../terminology/secret.md) 资源。
+以下属性可用于消费者或凭据上的配置。
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| key | string | 是 | | 非空 | 用于标识消费者凭据的唯一键。 |
+| secret | string | 否 | | 非空 | 算法为对称算法时，用于签名和验证 JWT 的共享密钥。使用 `HS256`、`HS384` 或 `HS512` 算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| public_key | string | 否 | | | RSA 或 ECDSA 公钥。当 `algorithm` 为 `RS256`、`ES256`、`RS384`、`RS512`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512` 或 `EdDSA` 时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| algorithm | string | 否 | HS256 | `HS256`、`HS384`、`HS512`、`RS256`、`RS384`、`RS512`、`ES256`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512`、`EdDSA` | 加密算法。 |
+| exp | integer | 否 | 86400 | >=1 | 令牌的过期时间，单位为秒。若不使用 APISIX 签发 JWT，则该参数会被忽略，签发时应在 payload 中指定过期时间。 |
+| base64_secret | boolean | 否 | false | | 若密钥经过 base64 编码，则设为 true。 |
+| lifetime_grace_period | integer | 否 | 0 | >=0 | 宽限期，单位为秒。用于处理生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
+| key_claim_name | string | 否 | key | | JWT payload 中用于标识关联密钥的声明，例如 `iss`。 |
+
+注意：Schema 中同时定义了 `encrypt_fields = {"secret"}`，这意味着该字段将在 etcd 中加密存储。详见[加密存储字段](../plugin-develop.md#encrypted-storage-fields)。
+
+以下属性可用于路由或服务上的配置。
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| header | string | 否 | authorization | | 用于获取令牌的请求头。 |
+| query | string | 否 | jwt | | 用于获取令牌的查询字符串。优先级低于 header。 |
+| cookie | string | 否 | jwt | | 用于获取令牌的 Cookie。优先级低于 query。 |
+| hide_credentials | boolean | 否 | false | | 若为 true，则不将携带 JWT 的 header、query 或 cookie 传递给上游服务。 |
+| anonymous_consumer | string | 否 | | | 匿名消费者名称。配置后，允许匿名用户绕过身份验证。 |
+| claims_to_verify | array[string] | 否 | ["exp", "nbf"] | `exp` 和 `nbf` 的组合 | 指定需要验证的 JWT 声明，以确保令牌在其允许的时间范围内使用。注意，这不是要求 payload 中必须存在的声明，而是在声明存在时进行验证。 |
+| store_in_ctx | boolean | 否 | false | | 若为 true，则将 JWT payload 存储在请求上下文变量 `ctx.jwt_auth_payload` 中，以便在同一请求中在 `jwt-auth` 之后执行的插件获取和使用 payload 信息。 |
+| realm | string | 否 | jwt | | 身份验证失败时，在 `WWW-Authenticate` 响应头中包含的 realm 值。 |
+
+您可以将 `jwt-auth` 与 [HashiCorp Vault](https://www.vaultproject.io/) 结合使用，通过 [APISIX Secret](../terminology/secret.md) 资源从其[加密 KV 引擎](https://developer.hashicorp.com/vault/docs/secrets/kv)中存储和获取密钥及 RSA 密钥对。
## 示例
-以下示例演示了如何在不同场景中使用 `jwt-auth` 插件。
+以下示例展示了如何针对不同场景使用 `jwt-auth` 插件。
:::note
-您可以这样从 `config.yaml` 中获取 `admin_key` 并存入环境变量：
+您可以通过以下命令从 `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:
This command hard-codes `/usr/local/apisix/conf/config.yaml`, while most other docs use `conf/config.yaml` (relative to the APISIX install dir). Consider reverting to `conf/config.yaml` or mentioning both paths to avoid breaking the copy-paste experience for non-default installs.
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -28,64 +28,81 @@ description: jwt-auth 插件支持使用 JSON Web Token (JWT) 作为客户端在
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/jwt-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`jwt-auth` 插件支持使用 [JSON Web Token (JWT)](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
+`jwt-auth` 插件支持使用 [JSON Web Token（JWT）](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
-启用后，该插件会公开一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自己。该令牌可以包含在请求 URL 查询字符串、请求标头或 cookie 中。然后，APISIX 将验证该令牌以确定是否应允许或拒绝请求访问上游资源。
+启用后，该插件会暴露一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自身。令牌可以包含在请求 URL 查询字符串、请求头或 Cookie 中。APISIX 随后会验证该令牌，以判断是否允许或拒绝请求访问上游资源。
-当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前向请求添加其他标头，例如 `X-Consumer-Username`、`X-Credential-Indentifier` 和其他消费者自定义标头（如已配置）。上游服务将能够区分消费者并根据需要实施其他逻辑。如果任何一个值不可用，则不会添加相应的标题。
+当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前，向请求添加额外的请求头，例如 `X-Consumer-Username`、`X-Credential-Identifier` 以及其他已配置的消费者自定义请求头。上游服务可据此区分消费者并根据需要实现额外逻辑。若某个值不可用，则不会添加对应的请求头。
## 属性
-Consumer/Credential 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------- | ------- | ----- | ------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| key | string | 是 | | | 消费者的唯一密钥。 |
-| secret | string | 否 | | | 当使用对称算法时，用于对 JWT 进行签名和验证的共享密钥。使用 `HS256` 或 `HS512` 作为算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| public_key | string | 否 | | | RSA 或 ECDSA 公钥， `algorithm` 属性选择 `RS256` 或 `ES256` 算法时必选。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| algorithm | string | 否 | "HS256" | ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "EdDSA"] | 加密算法。 |
-| exp | integer | 否 | 86400 | [1,...] | token 的超时时间。 |
-| base64_secret | boolean | 否 | false | | 当设置为 `true` 时，密钥为 base64 编码。 |
-| lifetime_grace_period | integer | 否 | 0 | [0,...] | 宽限期（以秒为单位）。用于解决生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
-| key_claim_name | string | 否 | key | | JWT payload 中的声明用于标识相关的秘密，例如 `iss`。 |
-
-注意：schema 中还定义了 `encrypt_fields = {"secret"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。
-
-Route 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 描述 |
-| ------ | ------ | ------ | ------------- |---------------------------------------------------------|
-| header | string | 否 | authorization | 设置我们从哪个 header 获取 token。 |
-| query | string | 否 | jwt | 设置我们从哪个 query string 获取 token，优先级低于 header。 |
-| cookie | string | 否 | jwt | 设置我们从哪个 cookie 获取 token，优先级低于 query。 |
-| hide_credentials | boolean | 否 | false | 如果为 true，则不要将 header、query 或带有 JWT 的 cookie 传递给上游服务。 |
-| 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` 标头中的域。|
-| claims_to_verify | array[string] | 否 | ["exp", "nbf"] | ["exp", "nbf"] | 需要在 JWT 负载中验证的声明。 |
-
-您可以使用 [HashiCorp Vault](https://www.vaultproject.io/) 实施 `jwt-auth`，以从其[加密的 KV 引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 使用 [APISIX Secret](../terminology/secret.md) 资源。
+以下属性可用于消费者或凭据上的配置。
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| key | string | 是 | | 非空 | 用于标识消费者凭据的唯一键。 |
+| secret | string | 否 | | 非空 | 算法为对称算法时，用于签名和验证 JWT 的共享密钥。使用 `HS256`、`HS384` 或 `HS512` 算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| public_key | string | 否 | | | RSA 或 ECDSA 公钥。当 `algorithm` 为 `RS256`、`ES256`、`RS384`、`RS512`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512` 或 `EdDSA` 时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| algorithm | string | 否 | HS256 | `HS256`、`HS384`、`HS512`、`RS256`、`RS384`、`RS512`、`ES256`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512`、`EdDSA` | 加密算法。 |
+| exp | integer | 否 | 86400 | >=1 | 令牌的过期时间，单位为秒。若不使用 APISIX 签发 JWT，则该参数会被忽略，签发时应在 payload 中指定过期时间。 |
+| base64_secret | boolean | 否 | false | | 若密钥经过 base64 编码，则设为 true。 |
+| lifetime_grace_period | integer | 否 | 0 | >=0 | 宽限期，单位为秒。用于处理生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
+| key_claim_name | string | 否 | key | | JWT payload 中用于标识关联密钥的声明，例如 `iss`。 |
Review Comment:
`key_claim_name` is documented under Consumer/Credential attributes, but it’s not part of the jwt-auth consumer credential schema. In code, `key_claim_name` is a Route/Service-level plugin config (used to locate the consumer key in the JWT payload). Please remove it from the Consumer/Credential table and add it to the Route/Service attributes table, updating the description to reflect that it identifies the claim containing the consumer key (not the secret).
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -32,46 +32,48 @@ description: The jwt-auth Plugin supports the use of JSON Web Token (JWT) as a m
<link rel="canonical" href="https://docs.api7.ai/hub/jwt-auth" />
</head>
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
The `jwt-auth` Plugin supports the use of [JSON Web Token (JWT)](https://jwt.io/) as a mechanism for clients to authenticate themselves before accessing Upstream resources.
Once enabled, the Plugin exposes an endpoint to create JWT credentials by [Consumers](../terminology/consumer.md). The process generates a token that client requests should carry to identify themselves to APISIX. The token can be included in the request URL query string, request header, or cookie. APISIX will then verify the token to determine if a request should be allowed or denied to access Upstream resources.
-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.
## Attributes
-For Consumer/Credential:
+The following attributes are available for configurations on Consumers or Credentials.
-| Name | Type | Required | Default | Valid values | Description |
-|---------------|---------|-------------------------------------------------------|---------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| key | string | True | | non-empty | Unique key for a Consumer. |
-| secret | string | False | | non-empty | Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256` or `HS512` as the algorithm. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
-| public_key | string | True if `RS256` or `ES256` is set for the `algorithm` attribute. | | | RSA or ECDSA public key. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
-| algorithm | string | False | HS256 | ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "EdDSA"] | Encryption algorithm. |
-| exp | integer | False | 86400 | [1,...] | Expiry time of the token in seconds. |
-| base64_secret | boolean | False | false | | Set to true if the secret is base64 encoded. |
-| lifetime_grace_period | integer | False | 0 | [0,...] | Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT. |
-| key_claim_name | string | False | key | | The claim in the JWT payload that identifies the associated secret, such as `iss`. |
+| Name | Type | Required | Default | Valid values | Description |
+|------|------|----------|---------|--------------|-------------|
+| key | string | True | | non-empty | A unique key that identifies the credential for a Consumer. |
+| secret | string | False | | non-empty | Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256`, `HS384`, or `HS512` as the algorithm. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
+| public_key | string | False | | | RSA or ECDSA public key. Required if the `algorithm` is `RS256`, `ES256`, `RS384`, `RS512`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, or `EdDSA`. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
+| algorithm | string | False | HS256 | `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, `EdDSA` | Encryption algorithm. |
+| exp | integer | False | 86400 | >=1 | Expiry time of the token in seconds. If you are not using APISIX to sign the JWT, this parameter is ignored and you should specify the expiration in the payload when signing the JWT. |
+| base64_secret | boolean | False | false | | Set to true if the secret is base64 encoded. |
+| lifetime_grace_period | integer | False | 0 | >=0 | Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT. |
+| key_claim_name | string | False | key | | The claim in the JWT payload that identifies the associated secret, such as `iss`. |
NOTE: `encrypt_fields = {"secret"}` is also defined in the schema, which means that the field will be stored encrypted in etcd. See [encrypted storage fields](../plugin-develop.md#encrypted-storage-fields).
-For Routes or Services:
+The following attributes are available for configurations on Routes or Services.
-| Name | Type | Required | Default | Description |
-|--------|--------|----------|---------------|---------------------------------------------------------------------|
-| header | string | False | authorization | The header to get the token from. |
-| query | string | False | jwt | The query string to get the token from. Lower priority than header. |
-| cookie | string | False | jwt | The cookie to get the token from. Lower priority than query. |
-| hide_credentials| boolean | False | false | If true, do not pass the header, query, or cookie with JWT to Upstream services. |
-| key_claim_name | string | False | key | The name of the JWT claim that contains the user key (corresponds to Consumer's key attribute). |
-| anonymous_consumer | string | False | false | Anonymous Consumer name. If configured, allow anonymous users to bypass the authentication. |
-| store_in_ctx | boolean | False | false | Set to true will store the JWT payload in the request context (`ctx.jwt_auth_payload`). This allows lower-priority plugins that run afterwards on the same request to retrieve and use the JWT token. |
-| realm | string | False | jwt | The realm to include in the `WWW-Authenticate` header when authentication fails. |
-| claims_to_verify | array[string] | False | ["exp", "nbf"] | ["exp", "nbf"] | The claims that need to be verified in the JWT payload. |
+| Name | Type | Required | Default | Valid values | Description |
+|------|------|----------|---------|--------------|-------------|
+| header | string | False | authorization | | The header to get the token from. |
+| query | string | False | jwt | | The query string to get the token from. Lower priority than header. |
+| cookie | string | False | jwt | | The cookie to get the token from. Lower priority than query. |
+| hide_credentials | boolean | False | false | | If true, do not pass the header, query, or cookie with JWT to Upstream services. |
+| anonymous_consumer | string | False | | | Anonymous Consumer name. If configured, allow anonymous users to bypass the authentication. |
+| claims_to_verify | array[string] | False | ["exp", "nbf"] | combination of `exp` and `nbf` | Specify the JWT claim(s) to verify, to ensure that the token is used within its allowed timeframe. Note that this is not the claims required to be presented in the payload, but the claims to verify, if presented. |
+| store_in_ctx | boolean | False | false | | If true, store JWT payload in the request context variable `ctx.jwt_auth_payload`. This allows plugins executed after `jwt-auth` on the same request to retrieve and use the payload information. |
Review Comment:
The Routes/Services attributes table is missing `key_claim_name`, but the plugin schema includes it with default `key` and it’s used to read the consumer key from the JWT payload. Please add a `key_claim_name` row here (and remove it from the Consumer/Credential table).
```suggestion
| store_in_ctx | boolean | False | false | | If true, store JWT payload in the request context variable `ctx.jwt_auth_payload`. This allows plugins executed after `jwt-auth` on the same request to retrieve and use the payload information. |
| key_claim_name | string | False | key | | The claim name in the JWT payload used to identify the consumer key. |
```
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -643,19 +1050,184 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
}'
```
-使用 `Authorization` 标头中的 JWT 向路由发送请求：
+</TabItem>
+
+<TabItem value="adc">
+
+创建使用 RS256 算法的 `jwt-auth` 凭据的消费者和启用了 `jwt-auth` 插件的路由：
+
+```yaml title="adc.yaml"
+consumers:
+ - username: jack
+ credentials:
+ - name: jwt-auth
+ type: jwt-auth
+ config:
+ key: jack-key
+ algorithm: RS256
+ public_key: |
+ -----BEGIN PUBLIC KEY-----
+ MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTxe7ZPycrEP0SK4OBA2
+ 0OUQsDN9gSFSHVvx/t++nZNrFxzZnV6q6/TRsihNXUIgwaOu5icFlIcxPL9Mf9UJ
+ a5/XCQExp1TxpuSmjkhIFAJ/x5zXrC8SGTztP3SjkhYnQO9PKVXI6ljwgakVCfpl
+ umuTYqI+ev7e45NdK8gJoJxPp8bPMdf8/nHfLXZuqhO/btrDg1x+j7frDNrEw+6B
+ CK2SsuypmYN+LwHfaH4Of7MQFk3LNIxyBz0mdbsKJBzp360rbWnQeauWtDymZxLT
+ ATRNBVyl3nCNsURRTkc7eyknLaDt2N5xTIoUGHTUFYSdE68QWmukYMVGcEHEEPkp
+ aQIDAQAB
+ -----END PUBLIC KEY-----
+services:
+ - name: jwt-auth-service
+ routes:
+ - name: jwt-route
+ uris:
+ - /headers
+ plugins:
+ jwt-auth: {}
+ upstream:
+ type: roundrobin
+ nodes:
+ - host: httpbin.org
+ port: 80
+ weight: 1
+```
+
+将配置同步到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="ingress">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX Ingress Controller', value: 'apisix-ingress-controller'}
+]}>
+
+<TabItem value="gateway-api">
+
+创建使用 RS256 算法的 `jwt-auth` 凭据的消费者和启用了 `jwt-auth` 插件的路由：
+
+```yaml title="jwt-auth-ic.yaml"
+apiVersion: apisix.apache.org/v1alpha1
+kind: Consumer
+metadata:
+ namespace: aic
+ name: jack
+spec:
+ gatewayRef:
+ name: apisix
+ credentials:
+ - type: jwt-auth
+ name: primary-cred
+ config:
+ key: jack-key
+ algorithm: RS256
+ public_key: |
+ -----BEGIN PUBLIC KEY-----
+ MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTxe7ZPycrEP0SK4OBA2
+ 0OUQsDN9gSFSHVvx/t++nZNrFxzZnV6q6/TRsihNXUIgwaOu5icFlIcxPL9Mf9UJ
+ a5/XCQExp1TxpuSmjkhIFAJ/x5zXrC8SGTztP3SjkhYnQO9PKVXI6ljwgakVCfpl
+ umuTYqI+ev7e45NdK8gJoJxPp8bPMdf8/nHfLXZuqhO/btrDg1x+j7frDNrEw+6B
+ CK2SsuypmYN+LwHfaH4Of7MQFk3LNIxyBz0mdbsKJBzp360rbWnQeauWtDymZxLT
+ ATRNBVyl3nCNsURRTkc7eyknLaDt2N5xTIoUGHTUFYSdE68QWmukYMVGcEHEEPkp
+ aQIDAQAB
+ -----END PUBLIC KEY-----
+---
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: httpbin-external-domain
+spec:
+ type: ExternalName
+ externalName: httpbin.org
+---
+apiVersion: apisix.apache.org/v1alpha1
+kind: PluginConfig
+metadata:
+ namespace: aic
+ name: jwt-auth-plugin-config
+spec:
+ plugins:
+ - name: jwt-auth
+ config:
+ _meta:
+ disable: false
+---
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+ namespace: aic
+ name: jwt-route
+spec:
+ parentRefs:
+ - name: apisix
+ rules:
+ - matches:
+ - path:
+ type: Exact
+ value: /headers
+ filters:
+ - type: ExtensionRef
+ extensionRef:
+ group: apisix.apache.org
+ kind: PluginConfig
+ name: jwt-auth-plugin-config
+ backendRefs:
+ - name: httpbin-external-domain
+ port: 80
+```
+
+将配置应用到集群：
+
+```shell
+kubectl apply -f jwt-auth-ic.yaml
+```
+
+</TabItem>
+
+<TabItem value="apisix-ingress-controller">
+
+ApisixConsumer CRD 存在一个已知问题，配置时会错误地要求提供 `private_key`。该问题将在后续版本中修复。目前，此示例无法通过 APISIX CRD 完成。
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+验证时，携带 JWT 在 `Authorization` 请求头中向路由发送请求：
```shell
curl -i "http://127.0.0.1:9080/headers" -H "Authorization: ${jwt_token}"
```
-您应该会收到 `HTTP/1.1 200 OK` 响应。
+您应收到 `HTTP/1.1 200 OK` 响应。
+
+### 在请求头中添加消费者自定义 ID
+
+以下示例演示如何在已验证请求的 `Consumer-Custom-Id` 请求头中附加消费者自定义 ID，以便根据需要实现额外逻辑。
Review Comment:
The header name here is inconsistent with what APISIX actually injects. In code, APISIX sets `X-Consumer-Custom-ID` (request header to upstream), not `Consumer-Custom-Id`. Please update the text to reference `X-Consumer-Custom-ID` (or at least include the `X-` prefix) for consistency with other injected headers like `X-Consumer-Username`.
```suggestion
以下示例演示如何在已验证请求的 `X-Consumer-Custom-ID` 请求头中附加消费者自定义 ID，以便根据需要实现额外逻辑。
```
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -82,7 +84,7 @@ The examples below demonstrate how you can work with the `jwt-auth` Plugin for d
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 command hard-codes `/usr/local/apisix/conf/config.yaml`, while most other docs use `conf/config.yaml`. Consider using the same path as the rest of the docs (or mentioning both) to avoid copy-paste failures for installations where APISIX is not under `/usr/local/apisix`.
```suggestion
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
```
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -28,64 +28,81 @@ description: jwt-auth 插件支持使用 JSON Web Token (JWT) 作为客户端在
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/jwt-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`jwt-auth` 插件支持使用 [JSON Web Token (JWT)](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
+`jwt-auth` 插件支持使用 [JSON Web Token（JWT）](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
-启用后，该插件会公开一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自己。该令牌可以包含在请求 URL 查询字符串、请求标头或 cookie 中。然后，APISIX 将验证该令牌以确定是否应允许或拒绝请求访问上游资源。
+启用后，该插件会暴露一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自身。令牌可以包含在请求 URL 查询字符串、请求头或 Cookie 中。APISIX 随后会验证该令牌，以判断是否允许或拒绝请求访问上游资源。
-当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前向请求添加其他标头，例如 `X-Consumer-Username`、`X-Credential-Indentifier` 和其他消费者自定义标头（如已配置）。上游服务将能够区分消费者并根据需要实施其他逻辑。如果任何一个值不可用，则不会添加相应的标题。
+当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前，向请求添加额外的请求头，例如 `X-Consumer-Username`、`X-Credential-Identifier` 以及其他已配置的消费者自定义请求头。上游服务可据此区分消费者并根据需要实现额外逻辑。若某个值不可用，则不会添加对应的请求头。
## 属性
-Consumer/Credential 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------- | ------- | ----- | ------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| key | string | 是 | | | 消费者的唯一密钥。 |
-| secret | string | 否 | | | 当使用对称算法时，用于对 JWT 进行签名和验证的共享密钥。使用 `HS256` 或 `HS512` 作为算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| public_key | string | 否 | | | RSA 或 ECDSA 公钥， `algorithm` 属性选择 `RS256` 或 `ES256` 算法时必选。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| algorithm | string | 否 | "HS256" | ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "EdDSA"] | 加密算法。 |
-| exp | integer | 否 | 86400 | [1,...] | token 的超时时间。 |
-| base64_secret | boolean | 否 | false | | 当设置为 `true` 时，密钥为 base64 编码。 |
-| lifetime_grace_period | integer | 否 | 0 | [0,...] | 宽限期（以秒为单位）。用于解决生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
-| key_claim_name | string | 否 | key | | JWT payload 中的声明用于标识相关的秘密，例如 `iss`。 |
-
-注意：schema 中还定义了 `encrypt_fields = {"secret"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。
-
-Route 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 描述 |
-| ------ | ------ | ------ | ------------- |---------------------------------------------------------|
-| header | string | 否 | authorization | 设置我们从哪个 header 获取 token。 |
-| query | string | 否 | jwt | 设置我们从哪个 query string 获取 token，优先级低于 header。 |
-| cookie | string | 否 | jwt | 设置我们从哪个 cookie 获取 token，优先级低于 query。 |
-| hide_credentials | boolean | 否 | false | 如果为 true，则不要将 header、query 或带有 JWT 的 cookie 传递给上游服务。 |
-| 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` 标头中的域。|
-| claims_to_verify | array[string] | 否 | ["exp", "nbf"] | ["exp", "nbf"] | 需要在 JWT 负载中验证的声明。 |
-
-您可以使用 [HashiCorp Vault](https://www.vaultproject.io/) 实施 `jwt-auth`，以从其[加密的 KV 引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 使用 [APISIX Secret](../terminology/secret.md) 资源。
+以下属性可用于消费者或凭据上的配置。
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| key | string | 是 | | 非空 | 用于标识消费者凭据的唯一键。 |
+| secret | string | 否 | | 非空 | 算法为对称算法时，用于签名和验证 JWT 的共享密钥。使用 `HS256`、`HS384` 或 `HS512` 算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| public_key | string | 否 | | | RSA 或 ECDSA 公钥。当 `algorithm` 为 `RS256`、`ES256`、`RS384`、`RS512`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512` 或 `EdDSA` 时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| algorithm | string | 否 | HS256 | `HS256`、`HS384`、`HS512`、`RS256`、`RS384`、`RS512`、`ES256`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512`、`EdDSA` | 加密算法。 |
+| exp | integer | 否 | 86400 | >=1 | 令牌的过期时间，单位为秒。若不使用 APISIX 签发 JWT，则该参数会被忽略，签发时应在 payload 中指定过期时间。 |
+| base64_secret | boolean | 否 | false | | 若密钥经过 base64 编码，则设为 true。 |
+| lifetime_grace_period | integer | 否 | 0 | >=0 | 宽限期，单位为秒。用于处理生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
+| key_claim_name | string | 否 | key | | JWT payload 中用于标识关联密钥的声明，例如 `iss`。 |
+
+注意：Schema 中同时定义了 `encrypt_fields = {"secret"}`，这意味着该字段将在 etcd 中加密存储。详见[加密存储字段](../plugin-develop.md#encrypted-storage-fields)。
+
+以下属性可用于路由或服务上的配置。
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| header | string | 否 | authorization | | 用于获取令牌的请求头。 |
+| query | string | 否 | jwt | | 用于获取令牌的查询字符串。优先级低于 header。 |
+| cookie | string | 否 | jwt | | 用于获取令牌的 Cookie。优先级低于 query。 |
+| hide_credentials | boolean | 否 | false | | 若为 true，则不将携带 JWT 的 header、query 或 cookie 传递给上游服务。 |
+| anonymous_consumer | string | 否 | | | 匿名消费者名称。配置后，允许匿名用户绕过身份验证。 |
+| claims_to_verify | array[string] | 否 | ["exp", "nbf"] | `exp` 和 `nbf` 的组合 | 指定需要验证的 JWT 声明，以确保令牌在其允许的时间范围内使用。注意，这不是要求 payload 中必须存在的声明，而是在声明存在时进行验证。 |
Review Comment:
The Route/Service attributes table is missing `key_claim_name`, but the plugin schema defines it (default `key`) and the plugin uses it to extract the consumer key from the JWT payload (`jwt.payload[conf.key_claim_name]`). Please add `key_claim_name` to this table (and remove it from the Consumer/Credential table).
```suggestion
| claims_to_verify | array[string] | 否 | ["exp", "nbf"] | `exp` 和 `nbf` 的组合 | 指定需要验证的 JWT 声明，以确保令牌在其允许的时间范围内使用。注意，这不是要求 payload 中必须存在的声明，而是在声明存在时进行验证。 |
| key_claim_name | string | 否 | key | | 用于从 JWT payload 中提取消费者 key 的声明名称。 |
```
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -32,46 +32,48 @@ description: The jwt-auth Plugin supports the use of JSON Web Token (JWT) as a m
<link rel="canonical" href="https://docs.api7.ai/hub/jwt-auth" />
</head>
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
The `jwt-auth` Plugin supports the use of [JSON Web Token (JWT)](https://jwt.io/) as a mechanism for clients to authenticate themselves before accessing Upstream resources.
Once enabled, the Plugin exposes an endpoint to create JWT credentials by [Consumers](../terminology/consumer.md). The process generates a token that client requests should carry to identify themselves to APISIX. The token can be included in the request URL query string, request header, or cookie. APISIX will then verify the token to determine if a request should be allowed or denied to access Upstream resources.
-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.
## Attributes
-For Consumer/Credential:
+The following attributes are available for configurations on Consumers or Credentials.
-| Name | Type | Required | Default | Valid values | Description |
-|---------------|---------|-------------------------------------------------------|---------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| key | string | True | | non-empty | Unique key for a Consumer. |
-| secret | string | False | | non-empty | Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256` or `HS512` as the algorithm. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
-| public_key | string | True if `RS256` or `ES256` is set for the `algorithm` attribute. | | | RSA or ECDSA public key. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
-| algorithm | string | False | HS256 | ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "EdDSA"] | Encryption algorithm. |
-| exp | integer | False | 86400 | [1,...] | Expiry time of the token in seconds. |
-| base64_secret | boolean | False | false | | Set to true if the secret is base64 encoded. |
-| lifetime_grace_period | integer | False | 0 | [0,...] | Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT. |
-| key_claim_name | string | False | key | | The claim in the JWT payload that identifies the associated secret, such as `iss`. |
+| Name | Type | Required | Default | Valid values | Description |
+|------|------|----------|---------|--------------|-------------|
+| key | string | True | | non-empty | A unique key that identifies the credential for a Consumer. |
+| secret | string | False | | non-empty | Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256`, `HS384`, or `HS512` as the algorithm. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
+| public_key | string | False | | | RSA or ECDSA public key. Required if the `algorithm` is `RS256`, `ES256`, `RS384`, `RS512`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, or `EdDSA`. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
+| algorithm | string | False | HS256 | `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, `EdDSA` | Encryption algorithm. |
+| exp | integer | False | 86400 | >=1 | Expiry time of the token in seconds. If you are not using APISIX to sign the JWT, this parameter is ignored and you should specify the expiration in the payload when signing the JWT. |
+| base64_secret | boolean | False | false | | Set to true if the secret is base64 encoded. |
+| lifetime_grace_period | integer | False | 0 | >=0 | Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT. |
+| key_claim_name | string | False | key | | The claim in the JWT payload that identifies the associated secret, such as `iss`. |
Review Comment:
`key_claim_name` is documented under Consumer/Credential attributes, but it’s not part of the jwt-auth consumer credential schema. In code, `key_claim_name` is a Route/Service-level plugin config (used to locate the consumer key in the JWT payload). Please remove it from the Consumer/Credential table and add it to the Route/Service attributes table, updating the description to reflect that it identifies the claim containing the consumer key (not the secret).
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -32,46 +32,48 @@ description: The jwt-auth Plugin supports the use of JSON Web Token (JWT) as a m
<link rel="canonical" href="https://docs.api7.ai/hub/jwt-auth" />
</head>
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
The `jwt-auth` Plugin supports the use of [JSON Web Token (JWT)](https://jwt.io/) as a mechanism for clients to authenticate themselves before accessing Upstream resources.
Once enabled, the Plugin exposes an endpoint to create JWT credentials by [Consumers](../terminology/consumer.md). The process generates a token that client requests should carry to identify themselves to APISIX. The token can be included in the request URL query string, request header, or cookie. APISIX will then verify the token to determine if a request should be allowed or denied to access Upstream resources.
-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.
## Attributes
-For Consumer/Credential:
+The following attributes are available for configurations on Consumers or Credentials.
-| Name | Type | Required | Default | Valid values | Description |
-|---------------|---------|-------------------------------------------------------|---------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| key | string | True | | non-empty | Unique key for a Consumer. |
-| secret | string | False | | non-empty | Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256` or `HS512` as the algorithm. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
-| public_key | string | True if `RS256` or `ES256` is set for the `algorithm` attribute. | | | RSA or ECDSA public key. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
-| algorithm | string | False | HS256 | ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "EdDSA"] | Encryption algorithm. |
-| exp | integer | False | 86400 | [1,...] | Expiry time of the token in seconds. |
-| base64_secret | boolean | False | false | | Set to true if the secret is base64 encoded. |
-| lifetime_grace_period | integer | False | 0 | [0,...] | Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT. |
-| key_claim_name | string | False | key | | The claim in the JWT payload that identifies the associated secret, such as `iss`. |
+| Name | Type | Required | Default | Valid values | Description |
+|------|------|----------|---------|--------------|-------------|
+| key | string | True | | non-empty | A unique key that identifies the credential for a Consumer. |
+| secret | string | False | | non-empty | Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256`, `HS384`, or `HS512` as the algorithm. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
+| public_key | string | False | | | RSA or ECDSA public key. Required if the `algorithm` is `RS256`, `ES256`, `RS384`, `RS512`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, or `EdDSA`. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
Review Comment:
`public_key` is described as “RSA or ECDSA public key”, but the algorithm list also includes `PS*` and `EdDSA`. To avoid implying EdDSA uses RSA/ECDSA keys, consider describing this field as the public key (PEM) required by the configured asymmetric algorithm, or splitting the description by algorithm families.
```suggestion
| public_key | string | False | | | Public key in PEM format required by the configured asymmetric algorithm. Required if the `algorithm` is `RS256`, `ES256`, `RS384`, `RS512`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, or `EdDSA`. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
```
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -28,64 +28,81 @@ description: jwt-auth 插件支持使用 JSON Web Token (JWT) 作为客户端在
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/jwt-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`jwt-auth` 插件支持使用 [JSON Web Token (JWT)](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
+`jwt-auth` 插件支持使用 [JSON Web Token（JWT）](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
-启用后，该插件会公开一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自己。该令牌可以包含在请求 URL 查询字符串、请求标头或 cookie 中。然后，APISIX 将验证该令牌以确定是否应允许或拒绝请求访问上游资源。
+启用后，该插件会暴露一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自身。令牌可以包含在请求 URL 查询字符串、请求头或 Cookie 中。APISIX 随后会验证该令牌，以判断是否允许或拒绝请求访问上游资源。
-当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前向请求添加其他标头，例如 `X-Consumer-Username`、`X-Credential-Indentifier` 和其他消费者自定义标头（如已配置）。上游服务将能够区分消费者并根据需要实施其他逻辑。如果任何一个值不可用，则不会添加相应的标题。
+当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前，向请求添加额外的请求头，例如 `X-Consumer-Username`、`X-Credential-Identifier` 以及其他已配置的消费者自定义请求头。上游服务可据此区分消费者并根据需要实现额外逻辑。若某个值不可用，则不会添加对应的请求头。
## 属性
-Consumer/Credential 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------- | ------- | ----- | ------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| key | string | 是 | | | 消费者的唯一密钥。 |
-| secret | string | 否 | | | 当使用对称算法时，用于对 JWT 进行签名和验证的共享密钥。使用 `HS256` 或 `HS512` 作为算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| public_key | string | 否 | | | RSA 或 ECDSA 公钥， `algorithm` 属性选择 `RS256` 或 `ES256` 算法时必选。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| algorithm | string | 否 | "HS256" | ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "EdDSA"] | 加密算法。 |
-| exp | integer | 否 | 86400 | [1,...] | token 的超时时间。 |
-| base64_secret | boolean | 否 | false | | 当设置为 `true` 时，密钥为 base64 编码。 |
-| lifetime_grace_period | integer | 否 | 0 | [0,...] | 宽限期（以秒为单位）。用于解决生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
-| key_claim_name | string | 否 | key | | JWT payload 中的声明用于标识相关的秘密，例如 `iss`。 |
-
-注意：schema 中还定义了 `encrypt_fields = {"secret"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。
-
-Route 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 描述 |
-| ------ | ------ | ------ | ------------- |---------------------------------------------------------|
-| header | string | 否 | authorization | 设置我们从哪个 header 获取 token。 |
-| query | string | 否 | jwt | 设置我们从哪个 query string 获取 token，优先级低于 header。 |
-| cookie | string | 否 | jwt | 设置我们从哪个 cookie 获取 token，优先级低于 query。 |
-| hide_credentials | boolean | 否 | false | 如果为 true，则不要将 header、query 或带有 JWT 的 cookie 传递给上游服务。 |
-| 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` 标头中的域。|
-| claims_to_verify | array[string] | 否 | ["exp", "nbf"] | ["exp", "nbf"] | 需要在 JWT 负载中验证的声明。 |
-
-您可以使用 [HashiCorp Vault](https://www.vaultproject.io/) 实施 `jwt-auth`，以从其[加密的 KV 引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 使用 [APISIX Secret](../terminology/secret.md) 资源。
+以下属性可用于消费者或凭据上的配置。
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| key | string | 是 | | 非空 | 用于标识消费者凭据的唯一键。 |
+| secret | string | 否 | | 非空 | 算法为对称算法时，用于签名和验证 JWT 的共享密钥。使用 `HS256`、`HS384` 或 `HS512` 算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| public_key | string | 否 | | | RSA 或 ECDSA 公钥。当 `algorithm` 为 `RS256`、`ES256`、`RS384`、`RS512`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512` 或 `EdDSA` 时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| algorithm | string | 否 | HS256 | `HS256`、`HS384`、`HS512`、`RS256`、`RS384`、`RS512`、`ES256`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512`、`EdDSA` | 加密算法。 |
+| exp | integer | 否 | 86400 | >=1 | 令牌的过期时间，单位为秒。若不使用 APISIX 签发 JWT，则该参数会被忽略，签发时应在 payload 中指定过期时间。 |
+| base64_secret | boolean | 否 | false | | 若密钥经过 base64 编码，则设为 true。 |
+| lifetime_grace_period | integer | 否 | 0 | >=0 | 宽限期，单位为秒。用于处理生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
+| key_claim_name | string | 否 | key | | JWT payload 中用于标识关联密钥的声明，例如 `iss`。 |
+
+注意：Schema 中同时定义了 `encrypt_fields = {"secret"}`，这意味着该字段将在 etcd 中加密存储。详见[加密存储字段](../plugin-develop.md#encrypted-storage-fields)。
Review Comment:
The link to the encrypted-fields section uses the English anchor `#encrypted-storage-fields`, but the Chinese `plugin-develop.md` section header is `## 加密存储字段`, so this anchor won’t resolve in the zh docs. Please update the anchor to match the actual heading in `docs/zh/latest/plugin-develop.md`.
```suggestion
注意：Schema 中同时定义了 `encrypt_fields = {"secret"}`，这意味着该字段将在 etcd 中加密存储。详见[加密存储字段](../plugin-develop.md#加密存储字段)。
```
##########
docs/zh/latest/plugins/jwt-auth.md:
##########
@@ -28,64 +28,81 @@ description: jwt-auth 插件支持使用 JSON Web Token (JWT) 作为客户端在
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/jwt-auth" />
+</head>
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## 描述
-`jwt-auth` 插件支持使用 [JSON Web Token (JWT)](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
+`jwt-auth` 插件支持使用 [JSON Web Token（JWT）](https://jwt.io/) 作为客户端在访问上游资源之前进行身份验证的机制。
-启用后，该插件会公开一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自己。该令牌可以包含在请求 URL 查询字符串、请求标头或 cookie 中。然后，APISIX 将验证该令牌以确定是否应允许或拒绝请求访问上游资源。
+启用后，该插件会暴露一个端点，供 [消费者](../terminology/consumer.md) 创建 JWT 凭据。该过程会生成一个令牌，客户端请求应携带该令牌以向 APISIX 标识自身。令牌可以包含在请求 URL 查询字符串、请求头或 Cookie 中。APISIX 随后会验证该令牌，以判断是否允许或拒绝请求访问上游资源。
-当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前向请求添加其他标头，例如 `X-Consumer-Username`、`X-Credential-Indentifier` 和其他消费者自定义标头（如已配置）。上游服务将能够区分消费者并根据需要实施其他逻辑。如果任何一个值不可用，则不会添加相应的标题。
+当消费者成功通过身份验证后，APISIX 会在将请求代理到上游服务之前，向请求添加额外的请求头，例如 `X-Consumer-Username`、`X-Credential-Identifier` 以及其他已配置的消费者自定义请求头。上游服务可据此区分消费者并根据需要实现额外逻辑。若某个值不可用，则不会添加对应的请求头。
## 属性
-Consumer/Credential 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ------------- | ------- | ----- | ------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| key | string | 是 | | | 消费者的唯一密钥。 |
-| secret | string | 否 | | | 当使用对称算法时，用于对 JWT 进行签名和验证的共享密钥。使用 `HS256` 或 `HS512` 作为算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| public_key | string | 否 | | | RSA 或 ECDSA 公钥， `algorithm` 属性选择 `RS256` 或 `ES256` 算法时必选。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| algorithm | string | 否 | "HS256" | ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "EdDSA"] | 加密算法。 |
-| exp | integer | 否 | 86400 | [1,...] | token 的超时时间。 |
-| base64_secret | boolean | 否 | false | | 当设置为 `true` 时，密钥为 base64 编码。 |
-| lifetime_grace_period | integer | 否 | 0 | [0,...] | 宽限期（以秒为单位）。用于解决生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
-| key_claim_name | string | 否 | key | | JWT payload 中的声明用于标识相关的秘密，例如 `iss`。 |
-
-注意：schema 中还定义了 `encrypt_fields = {"secret"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。
-
-Route 端：
-
-| 名称 | 类型 | 必选项 | 默认值 | 描述 |
-| ------ | ------ | ------ | ------------- |---------------------------------------------------------|
-| header | string | 否 | authorization | 设置我们从哪个 header 获取 token。 |
-| query | string | 否 | jwt | 设置我们从哪个 query string 获取 token，优先级低于 header。 |
-| cookie | string | 否 | jwt | 设置我们从哪个 cookie 获取 token，优先级低于 query。 |
-| hide_credentials | boolean | 否 | false | 如果为 true，则不要将 header、query 或带有 JWT 的 cookie 传递给上游服务。 |
-| 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` 标头中的域。|
-| claims_to_verify | array[string] | 否 | ["exp", "nbf"] | ["exp", "nbf"] | 需要在 JWT 负载中验证的声明。 |
-
-您可以使用 [HashiCorp Vault](https://www.vaultproject.io/) 实施 `jwt-auth`，以从其[加密的 KV 引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 使用 [APISIX Secret](../terminology/secret.md) 资源。
+以下属性可用于消费者或凭据上的配置。
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------|------|--------|--------|--------|------|
+| key | string | 是 | | 非空 | 用于标识消费者凭据的唯一键。 |
+| secret | string | 否 | | 非空 | 算法为对称算法时，用于签名和验证 JWT 的共享密钥。使用 `HS256`、`HS384` 或 `HS512` 算法时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
+| public_key | string | 否 | | | RSA 或 ECDSA 公钥。当 `algorithm` 为 `RS256`、`ES256`、`RS384`、`RS512`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512` 或 `EdDSA` 时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
Review Comment:
`public_key` is described as an “RSA or ECDSA public key” but the valid algorithms listed include `PS*` and `EdDSA` too. To avoid misleading users (e.g., EdDSA is not RSA/ECDSA), consider describing this field generically as the public key (PEM) used by the configured asymmetric algorithm, or explicitly enumerating key types per algorithm family.
```suggestion
| public_key | string | 否 | | | 由所配置非对称算法使用的公钥（PEM 格式）。当 `algorithm` 为 `RS256`、`ES256`、`RS384`、`RS512`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512` 或 `EdDSA` 时必填。该字段支持使用 [APISIX Secret](../terminology/secret.md) 资源将值保存在 Secret Manager 中。 |
```
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -659,6 +1216,17 @@ You should receive an `HTTP/1.1 200 OK` response.
The following example demonstrates how you can attach a Consumer custom ID to authenticated request in the `Consumer-Custom-Id` header, which can be used to implement additional logics as needed.
Review Comment:
APISIX injects `X-Consumer-Custom-ID` (see `apisix/consumer.lua`), but this text refers to `Consumer-Custom-Id`. Please update the documentation to use `X-Consumer-Custom-ID` (or include the `X-` prefix) for consistency with the actual header name.
```suggestion
The following example demonstrates how you can attach a Consumer custom ID to authenticated request in the `X-Consumer-Custom-ID` header, which can be used to implement additional logics as needed.
```
--
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(jwt-auth): re-port with Admin API, ADC, and Ingress Controller tabs [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn merged PR #13248:
URL: https://github.com/apache/apisix/pull/13248
--
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(jwt-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 #13248:
URL: https://github.com/apache/apisix/pull/13248#discussion_r3109664831
##########
docs/en/latest/plugins/jwt-auth.md:
##########
@@ -32,57 +32,59 @@ description: The jwt-auth Plugin supports the use of JSON Web Token (JWT) as a m
<link rel="canonical" href="https://docs.api7.ai/hub/jwt-auth" />
</head>
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
## Description
The `jwt-auth` Plugin supports the use of [JSON Web Token (JWT)](https://jwt.io/) as a mechanism for clients to authenticate themselves before accessing Upstream resources.
Once enabled, the Plugin exposes an endpoint to create JWT credentials by [Consumers](../terminology/consumer.md). The process generates a token that client requests should carry to identify themselves to APISIX. The token can be included in the request URL query string, request header, or cookie. APISIX will then verify the token to determine if a request should be allowed or denied to access Upstream resources.
-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.
## Attributes
-For Consumer/Credential:
+The following attributes are available for configurations on Consumers or Credentials.
-| Name | Type | Required | Default | Valid values | Description |
-|---------------|---------|-------------------------------------------------------|---------|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| key | string | True | | non-empty | Unique key for a Consumer. |
-| secret | string | False | | non-empty | Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256` or `HS512` as the algorithm. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
-| public_key | string | True if `RS256` or `ES256` is set for the `algorithm` attribute. | | | RSA or ECDSA public key. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
-| algorithm | string | False | HS256 | ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "ES256", "ES384", "ES512", "PS256", "PS384", "PS512", "EdDSA"] | Encryption algorithm. |
-| exp | integer | False | 86400 | [1,...] | Expiry time of the token in seconds. |
-| base64_secret | boolean | False | false | | Set to true if the secret is base64 encoded. |
-| lifetime_grace_period | integer | False | 0 | [0,...] | Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT. |
-| key_claim_name | string | False | key | | The claim in the JWT payload that identifies the associated secret, such as `iss`. |
+| Name | Type | Required | Default | Valid values | Description |
+|------|------|----------|---------|--------------|-------------|
+| key | string | True | | non-empty | A unique key that identifies the credential for a Consumer. |
+| secret | string | False | | non-empty | Shared key used to sign and verify the JWT when the algorithm is symmetric. Required when using `HS256`, `HS384`, or `HS512` as the algorithm. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
+| public_key | string | False | | | Public key in PEM format required by the configured asymmetric algorithm. Required if the `algorithm` is `RS256`, `ES256`, `RS384`, `RS512`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, or `EdDSA`. This field supports saving the value in Secret Manager using the [APISIX Secret](../terminology/secret.md) resource. |
+| algorithm | string | False | HS256 | `HS256`, `HS384`, `HS512`, `RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, `PS256`, `PS384`, `PS512`, `EdDSA` | Encryption algorithm. |
+| exp | integer | False | 86400 | >=1 | Expiry time of the token in seconds. If you are not using APISIX to sign the JWT, this parameter is ignored and you should specify the expiration in the payload when signing the JWT. |
+| base64_secret | boolean | False | false | | Set to true if the secret is base64 encoded. |
+| lifetime_grace_period | integer | False | 0 | >=0 | Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT. |
NOTE: `encrypt_fields = {"secret"}` is also defined in the schema, which means that the field will be stored encrypted in etcd. See [encrypted storage fields](../plugin-develop.md#encrypted-storage-fields).
-For Routes or Services:
+The following attributes are available for configurations on Routes or Services.
-| Name | Type | Required | Default | Description |
-|--------|--------|----------|---------------|---------------------------------------------------------------------|
-| header | string | False | authorization | The header to get the token from. |
-| query | string | False | jwt | The query string to get the token from. Lower priority than header. |
-| cookie | string | False | jwt | The cookie to get the token from. Lower priority than query. |
-| hide_credentials| boolean | False | false | If true, do not pass the header, query, or cookie with JWT to Upstream services. |
-| key_claim_name | string | False | key | The name of the JWT claim that contains the user key (corresponds to Consumer's key attribute). |
-| anonymous_consumer | string | False | false | Anonymous Consumer name. If configured, allow anonymous users to bypass the authentication. |
-| store_in_ctx | boolean | False | false | Set to true will store the JWT payload in the request context (`ctx.jwt_auth_payload`). This allows lower-priority plugins that run afterwards on the same request to retrieve and use the JWT token. |
-| realm | string | False | jwt | The realm to include in the `WWW-Authenticate` header when authentication fails. |
-| claims_to_verify | array[string] | False | ["exp", "nbf"] | ["exp", "nbf"] | The claims that need to be verified in the JWT payload. |
+| Name | Type | Required | Default | Valid values | Description |
+|------|------|----------|---------|--------------|-------------|
+| header | string | False | authorization | | The header to get the token from. |
+| query | string | False | jwt | | The query string to get the token from. Lower priority than header. |
+| cookie | string | False | jwt | | The cookie to get the token from. Lower priority than query. |
+| hide_credentials | boolean | False | false | | If true, do not pass the header, query, or cookie with JWT to Upstream services. |
+| anonymous_consumer | string | False | | | Anonymous Consumer name. If configured, allow anonymous users to bypass the authentication. |
+| claims_to_verify | array[string] | False | ["exp", "nbf"] | combination of `exp` and `nbf` | Specify the JWT claim(s) to verify, to ensure that the token is used within its allowed timeframe. Note that this is not the claims required to be presented in the payload, but the claims to verify, if presented. |
+| store_in_ctx | boolean | False | false | | If true, store JWT payload in the request context variable `ctx.jwt_auth_payload`. This allows plugins executed after `jwt-auth` on the same request to retrieve and use the payload information. |
+| realm | string | False | jwt | | The realm to include in the `WWW-Authenticate` header when authentication fails. |
+| key_claim_name | string | False | key | | The claim in the JWT payload that identifies the associated secret, such as `iss`. |
-You can implement `jwt-auth` with [HashiCorp Vault](https://www.vaultproject.io/) to store and fetch secrets and RSA keys pairs from its [encrypted KV engine](https://developer.hashicorp.com/vault/docs/secrets/kv) using the [APISIX Secret](../terminology/secret.md) resource.
+You can implement `jwt-auth` with [HashiCorp Vault](https://www.vaultproject.io/) to store and fetch secrets and RSA key pairs from its [encrypted KV engine](https://developer.hashicorp.com/vault/docs/secrets/kv) using the [APISIX Secret](../terminology/secret.md) resource.
## Examples
The examples below demonstrate how you can work with the `jwt-auth` Plugin for different scenarios.
:::note
-You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
+You can fetch the `admin_key` from `/conf/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' /conf/config.yaml | sed 's/"//g')
Review Comment:
`/conf/config.yaml` looks like a container-internal absolute path. In the rest of the APISIX docs, these setup snippets use `conf/config.yaml`, and using `/conf/...` on a normal checkout will fail because that file does not exist at the filesystem root. Could we switch this back to `conf/config.yaml` here (and in the mirrored examples) so the command works in local/source installs?
--
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