JWT Auth Configuration

Configuration reference for the JWT Auth plugin (`jwt-auth`): the parameters on credentials and routes or services, each attribute with its type, whether it is required, its default and its accepted values.

Parameters

See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.

Credentials

The following are plugin attributes available for configurations on credentials (opens in Apache APISIX docs).

key — string · required · since APISIX 1.2 · API7 Gateway 3.2.16.3

Valid values: non-empty

A unique key that identifies the credential for a consumer.

secret — string · optional · since APISIX 1.2 · API7 Gateway 3.2.16.3

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 (opens in Apache APISIX docs).

public_key — string · optional · since APISIX 2.1 · API7 Gateway 3.2.16.3

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 · since APISIX 1.2 · API7 Gateway 3.2.16.3

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 · since APISIX 1.2 · API7 Gateway 3.2.16.3

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 · since APISIX 1.2 · API7 Gateway 3.2.16.3

Set to true if the secret is base64 encoded.

lifetime_grace_period — integer · optional · default: 0 · since APISIX 2.99.0 · API7 Gateway 3.2.16.3

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 (opens in Apache APISIX docs) or services (opens in Apache APISIX docs).

header — string · optional · default: authorization · since APISIX 2.13.0 · API7 Gateway 3.2.16.3

The header to get the token from.

query — string · optional · default: jwt · since APISIX 2.13.0 · API7 Gateway 3.2.16.3

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

hide_credentials — boolean · optional · default: false · since APISIX 3.1.0 · API7 Gateway 3.2.16.3

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

anonymous_consumer — string · optional · since APISIX 3.12.0 · API7 Gateway 3.2.16.3

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 · since APISIX 3.16.0 · API7 Gateway 3.2.16.4

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 · since APISIX 3.12.0 · API7 Gateway 3.2.16.4

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

store_in_ctx — boolean · optional · default: false · since APISIX 3.12.0 · API7 Gateway 3.8.9

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 · since APISIX 3.15.0 · API7 Gateway 3.9.2

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.