Skip to main content
API7.ai Logo

Parameters​

See plugin common configurations for configuration options available to all plugins.

Credentials​

The following are plugin attributes available for configurations on credentials.

  • key

    string

    required

    vaild vaule:

    non-empty

    A unique key that identifies the credential for a consumer.

  • secret

    string

    vaild vaule:

    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.

    The secret is encrypted with AES before being stored in etcd. You can also store it in an environment variable and reference it using the env:// prefix, or in a secret manager such as HashiCorp Vault's KV secrets engine, and reference it using the secret:// prefix. For more information, see secrets.

  • public_key

    string

    RSA or ECDSA public key. Required if the algorithm is RS256, ES256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512, or EdDSA.

  • algorithm

    string

    default: HS256

    vaild vaule:

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

    Algorithm used to sign and verify the token. The alg value in the JWT header must exactly match this configured value; a mismatch is rejected with 401 Unauthorized.

  • exp

    integer

    default: 86400

    vaild vaule:

    greater than or equal to 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

    default: false

    Set to true if the secret is base64 encoded.

  • lifetime_grace_period

    integer

    default: 0

    vaild vaule:

    greater than or equal to 0

    Grace period in seconds. Used to account for clock skew between the server generating the JWT and the server validating the JWT.

Routes or Services​

The following are plugin attributes available for configurations on routes or services.

  • header

    string

    default: authorization

    The header to get the token from.

  • query

    string

    default: jwt

    The query string to get the token from. Lower priority than header.

  • cookie

    string

    default: jwt

    The cookie to get the token from. Lower priority than query.

  • hide_credentials

    boolean

    default: false

    If true, do not pass the header, query, or cookie with JWT to upstream services.

  • anonymous_consumer

    string

    Anonymous consumer name. If configured, allow anonymous users to bypass the authentication. See Rate Limit with Anonymous Consumer for more details.

  • claims_to_verify

    array[string]

    vaild vaule:

    combination of exp and nbf

    Claims used to verify that the token is within its allowed time window.

    A nonempty list makes every listed claim required. A token missing a configured claim is rejected.

    When this option is unset or empty, exp and nbf are validated whenever they are present, but neither claim is required.

    These validation rules were introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0.

  • key_claim_name

    string

    default: key

    The claim in the JWT payload that identifies the associated secret, such as iss.

  • store_in_ctx

    boolean

    default: 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. For instance, to retrieve the key in the payload, you can use ctx.jwt_auth_payload.key.

    Supported in APISIX and from Enterprise 3.8.9.

  • realm

    string

    default: jwt

    Realm in the WWW-Authenticate response header returned with a 401 Unauthorized response due to authentication failure. For example:

    • If realm is set to jwt-auth, the 401 response will include the following header:

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

    • If realm is not configured, the 401 response will include the following header:

      WWW-Authenticate: Bearer realm="jwt"

    This parameter is available in API7 Enterprise version 3.9.2 and later, and in Apache APISIX version 3.15.0 and later.