跳到主要内容

参数​

请参阅 插件通用配置 了解所有插件可用的配置选项。

凭据​

以下是可在 凭据 上配置的插件属性。

  • key

    string

    required

    vaild vaule:

    non-empty

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

  • secret

    string

    vaild vaule:

    non-empty

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

    该密钥在存储到 etcd 之前会使用 AES 加密。你也可以将其存储在环境变量中并使用 env:// 前缀引用，或者存储在如 HashiCorp Vault 的 KV secrets engine 等密钥管理器中，并使用 secret:// 前缀引用。更多信息请参考 Secrets。

  • public_key

    string

    RSA 或 ECDSA 公钥。如果 algorithm 为 RS256、ES256、RS384、RS512、ES256、ES384、ES512、PS256、PS384、PS512 或 EdDSA，则此项必填。

  • algorithm

    string

    default: HS256

    vaild vaule:

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

    加密算法。

    目前 APISIX 仅支持 HS256、HS512、RS256 和 ES256。企业版支持所有算法。

  • exp

    integer

    default: 86400

    vaild vaule:

    大于或等于 1

    令牌的过期时间（秒）。

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

  • base64_secret

    boolean

    default: false

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

  • lifetime_grace_period

    integer

    default: 0

    vaild vaule:

    大于或等于 0

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

路由或服务​

以下是可在 路由 或 服务 上配置的插件属性。

  • header

    string

    default: authorization

    获取令牌的请求头。

  • query

    string

    default: jwt

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

  • cookie

    string

    default: jwt

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

  • hide_credentials

    boolean

    default: false

    如果为 true，则不将带有 JWT 的请求头、查询字符串或 Cookie 传递给上游服务。

  • anonymous_consumer

    string

    匿名消费者名称。如果配置了此项，允许匿名用户绕过认证。详情请参考 匿名消费者的速率限制。

  • claims_to_verify

    array[string]

    vaild vaule:

    combination of exp and nbf

    指定要验证的 JWT Claim(s)，以确保证令牌在允许的时间范围内使用。注意，这不是 payload 中必须出现的 claim，而是如果出现则需要验证的 payload。

    默认情况下，APISIX 要求 JWT payload 中必须出现 exp 和 nbf 中的一个，在 API7 企业版中不需要。

  • key_claim_name

    string

    default: key

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

  • store_in_ctx

    boolean

    default: false

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

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

  • realm

    string

    default: jwt

    认证失败时返回的 401 Unauthorized 响应中 WWW-Authenticate 响应头的 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 及更高版本中可用。