JWT Policy

Overview

JWT (JSON Web Token) policy is used to validate the token included in API requests. It ensures that only users with valid tokens, generated using the correct JWT KEY and SECRET of the project, can access the API.

This policy supports token validation based on selected paths using either RequiredPath or NotRequiredPath mode. Additionally, it can be combined with the tokenBlacklistLogoutPath function to invalidate tokens upon logout.

Supported Algorithms:

• HS256 (HMAC SHA-256)
• RS256 (RSA SHA-256)

JWT Token Rules

To successfully authenticate a JWT token in APIM:

• The JWT Token must be included in the Authorization header:

Authorization: bearer JWT_TOKEN

• The token’s payload must contain:
  • "apim_key_claim_name" with the project’s JWT KEY.
  • "exp" field to indicate token expiration time.

Example Payload:

"apim_key_claim_name": "64c44d593be841bcec7fe768184e4c7e",
"exp": 1900000000

Example Header:

"alg": "HS256",
"typ": "JWT"

JWT Sample Token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhcGltX2tleV9jbGFpbV9uYW1lIjoiNjRjNDRkNTkzYmU4NDFiY2VjN2ZlNzY4MTg0ZTRjN2UiLCJleHAiOjE5MDAwMDAwMDB9.1kB5k-vM2Cef7ZYTyJUQ-LsDUmG4K7sJUfrJ3FqgYxQ

Configuration Details

JWT Path Matching

JWT verification can be applied to selected paths using two modes:

Option	Description
RequiredPath	Apply JWT authentication only to the listed method/path pairs. All other paths will not require JWT.
NotRequiredPath	Apply JWT authentication to all paths except the ones listed.

note

Only one mode (RequiredPath or NotRequiredPath) can be used at a time. Switching modes will reset previous settings.

Input Format:

Method_Path

Examples:

GET_/v1/test
Applies to GET requests at /v1/test

POST_/v1/example
Applies to POST at /v1/example

ANY_/v1/apis
Applies to all HTTP methods at /v1/apis

GET_/v1/apis*
Applies to all subpaths under /v1/apis (e.g., /v1/apis/a)

tokenBlacklistLogoutPath

This feature allows APIM to blacklist a JWT token when a logout request is made and successfully returns HTTP 200 from the API Gateway.

Toggle Field:

Field	Description
useJWTBlacklistRevoking	When enabled, JWT tokens will be added to the blacklist storage upon logout response. This prevents further use of the same token.

note

Cannot be changed: Toggle to prevent this policy from being removed.

Cannot change the setting value: Toggle to prevent changes to the configuration values after setup.

Redis Configuration (used to store blacklisted tokens)

Option 1: APIMRedis - Default system Redis; no manual configuration needed.

Option 2: CustomRedis

Configuration Field	Description
Redis Host	Address of the Redis server (e.g., 127.0.0.1).
Redis Port	Port number of the Redis server (e.g., 6379).
Redis Password	Password for authentication.
Redis Database	Specifies which database index to use (e.g., 1).
Redis Pool Size	Maximum number of connections in the Redis connection pool (default: 1000).
Redis Pool Backlog	Maximum number of requests waiting for an available connection (default: 30).

Option 3: RedisCluster

Configuration Field	Description
Redis Cluster Nodes	The cluster node addresses (e.g., redis-cluster.apim:6379).
Redis Cluster Password	Password for authentication.
Redis Cluster Name	Specifies the cluster name (e.g., kong_redis_cluster).
Redis Connect Timeout	Timeout for establishing a Redis connection (default: 1000ms).
Redis Read Timeout	Timeout for reading data from Redis (default: 1000ms).
Redis Send Timeout	Timeout for sending data to Redis (default: 1000ms).
Redis Pool Size	Maximum number of connections in the Redis connection pool (default: 1000).
Redis Pool Backlog	Maximum number of pending connections (default: 30).
Redis Keepalive Timeout	Maximum idle time before Redis connection is closed (default: 55000ms).