跳到主要内容

参数​

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

凭据​

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

  • key

    string

    必填

    有效值：

    非空

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

  • secret

    string

    有效值：

    非空

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

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

  • public_key

    string

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

  • 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

    令牌的过期时间（秒）。

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

  • base64_secret

    boolean

    默认值：false

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

  • lifetime_grace_period

    integer

    默认值：0

    有效值：

    大于或等于 0

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

路由或服务​

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

  • header

    string

    默认值：authorization

    获取令牌的请求头。

  • query

    string

    默认值：jwt

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

  • cookie

    string

    默认值：jwt

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

  • hide_credentials

    boolean

    默认值：false

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

  • anonymous_consumer

    string

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

  • claims_to_verify

    array[string]

    有效值：

    exp 和 nbf 的组合

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

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

    当此选项未设置或为空时，APISIX 会校验已存在的 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 响应头的 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 及更高版本中可用。