# JWT Auth 配置选项

jwt-auth 插件在代理请求之前，通过验证请求头、查询参数或 Cookie 中签名的 JSON Web Token 来认证消费者。<!-- --> <!-- -->配置涵盖凭据字段和路由和服务字段。

## 参数[​](#参数 "参数的直接链接")

请参阅 [插件通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md) 了解所有插件可用的配置选项。

### 凭据[​](#凭据 "凭据的直接链接")

以下是可在 [凭据](https://docs.apiseven.com/apisix/key-concepts/credentials.md) 上配置的插件属性。

* key

  string

  必填

  有效值：

  非空

  ***

  唯一标识消费者凭据的密钥。

* secret

  string

  有效值：

  非空

  ***

  算法为对称时用于签名和验证 JWT 的共享密钥。当使用 `HS256`、`HS384` 或 `HS512` 作为算法时必填。

  该密钥在存储到 etcd 之前会使用 AES 加密。你也可以将其存储在环境变量中并使用 `$env://` 前缀引用，或者存储在如 HashiCorp Vault 的 [KV 密钥引擎](https://developer.hashicorp.com/vault/docs/secrets/kv) 等密钥管理器中，并使用 `$secret://` 前缀引用。这些网关引用在运行时解析。ADC 的 `${NAME}` 插值有所不同：ADC 在同步前加载配置文件时解析插值。更多信息请参考[密钥](https://docs.apiseven.com/apisix/key-concepts/secrets.md)。

* public\_key

  string

  ***

  用于验证采用非对称算法签名的 JWT 的公钥。所有受支持的非 HMAC 算法均要求配置此项。

* algorithm

  string

  默认值：`HS256`

  有效值：

  `HS256`、`HS384`、`HS512`、`RS256`、`RS384`、`RS512`、`ES256`、`ES384`、`ES512`、`PS256`、`PS384`、`PS512`、`EdDSA`

  ***

  用于签名和验证 Token 的算法。JWT Header 中的 `alg` 值必须与此配置值完全一致；不一致时会返回 `401 Unauthorized`。

* exp

  integer

  默认值：`86400`

  有效值：

  大于或等于 1

  ***

  Token 的过期时间（秒）。

  如果你不使用 APISIX 签署 JWT，则忽略此参数，你应该在签署 JWT 时在 payload 中指定过期时间。

* base64\_secret

  boolean

  默认值：`false`

  ***

  如果密钥是 base64 编码的，则设置为 true。

* lifetime\_grace\_period

  integer

  默认值：`0`

  有效值：

  大于或等于 0

  ***

  宽限期（秒）。用于解决生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。

### 路由或服务[​](#路由或服务 "路由或服务的直接链接")

以下是可在 [路由](https://docs.apiseven.com/apisix/key-concepts/routes.md) 或 [服务](https://docs.apiseven.com/apisix/key-concepts/services.md) 上配置的插件属性。

* header

  string

  默认值：`authorization`

  ***

  获取 Token 的请求头。

* query

  string

  默认值：`jwt`

  ***

  获取 Token 的查询字符串。优先级低于请求头。

* cookie

  string

  默认值：`jwt`

  ***

  获取 Token 的 Cookie。优先级低于查询字符串。

* hide\_credentials

  boolean

  默认值：`false`

  ***

  如果为 true，则在转发到上游前，从用于认证的选定来源中移除 JWT。来源按请求头、查询参数、Cookie 的顺序检查。优先级较低的重复凭据不会被移除。

* anonymous\_consumer

  string

  ***

  匿名消费者名称。如果配置了此项，允许匿名用户绕过认证。详情请参考 [匿名消费者的速率限制](https://docs.apiseven.com/hub/jwt-auth.md#匿名消费者的速率限制)。

* claims\_to\_verify

  array\[string]

  有效值：

  `exp` 和 `nbf` 的组合

  ***

  用于验证 Token 是否位于允许时间窗口内的 Claim。

  非空列表会要求必须提供并校验列表中的每个 Claim。缺少任一已配置 Claim 的 Token 都会被拒绝。

  当此选项未设置或为空时，插件会校验已存在的 `exp` 和 `nbf`，但不要求必须提供这两个 Claim。

  这些校验规则自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.17.0 起引入。

* key\_claim\_name

  string

  默认值：`key`

  ***

  JWT Payload 中标识关联密钥的 Claim，例如 `iss`。

* store\_in\_ctx

  boolean

  默认值：`false`

  ***

  如果为 true，将 JWT Payload 存储在请求上下文变量 `ctx.jwt_auth_payload` 中。这允许在同一请求中 `jwt-auth` 之后执行的插件检索和使用 payload 信息。例如，要在 payload 中检索密钥，可以使用 `ctx.jwt_auth_payload.key`。

  支持版本：APISIX 以及企业版 3.8.9 起。

* realm

  string

  默认值：`jwt`

  ***

  身份认证失败时返回的 `401 Unauthorized` 响应中 [`WWW-Authenticate`](https://datatracker.ietf.org/doc/html/rfc7235#section-4.1) 响应头的 Realm。例如：

  * 如果 `realm` 设置为 `jwt-auth`，401 响应将包含以下响应头：

    ```
    WWW-Authenticate: Bearer realm="jwt-auth"
    ```

  * 如果未配置 `realm`，401 响应将包含以下响应头：

    ```
    WWW-Authenticate: Bearer realm="jwt"
    ```

  该参数在 API7 企业版版本 3.9.2 及更高版本，以及 Apache APISIX 版本 3.15.0 及更高版本中可用。
