JWT Auth Configuration

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

  Valid values: non-empty

  A unique key that identifies the credential for a consumer.

• secret — string · optional

  Valid values: 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 · optional

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

• algorithm — string · optional · default: HS256

  Valid values: 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 · optional · default: 86400

  Valid values: 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 · optional · default: false

  Set to true if the secret is base64 encoded.

• lifetime_grace_period — integer · optional · default: 0

  Valid values: 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 · optional · default: authorization

  The header to get the token from.

• query — string · optional · default: jwt

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

• cookie — string · optional · default: jwt

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

• hide_credentials — boolean · optional · default: false

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

• anonymous_consumer — string · optional

  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] · optional

  Valid values: 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 · optional · default: key

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

• store_in_ctx — boolean · optional · 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 · optional · 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.