The JSON Web Token (JWT) is an open standard that allows information to be transferred securely between different parties. The token is digitally signed by using a private key (HMAC) or a public/private key (RSA) by building a JSON Web Signature (JWS). It guarantees that the JWT hasn’t been modified since its creation.
The main benefits of a JWT are:
Here are the main use cases in which the Kong Gateway should craft and sign a custom JWT:
The structure of a JWT is based on three parts separated by a dot: header.payload.signature
header: there is at least the token type (JWT) and the signing algorithm (HMAC or RSA)payload: there is information, called claims, for instance, the client_id.signature: calculated by encoding the header and payload and signed by the algorithm specified in the headerWe propose the x-custom-jwt custom plugin for covering the use cases mentioned above. The mechanism of the plugin is:
The x-custom-jwt plugin doesn't check the validity of the Consumer’s authentication itself (it also doesn't check JWT signature & JWT expiration, user/password checking, Client TLS checking, or API key checking). So it's mandatory to use this plugin in conjunction with one of Kong's security plugins.
Depending on the enabled security plugin, the x-custom-jwt.client_id value varies:
client_id=clientId (default input claim and configurable)client_id=UserNameclient_id=subjectDNclient_id=ApiKeyThe backend API verifies the new JWT by downloading the public JWKS (JSON Web Key Sets) delivered by a Kong route and a Request Termination plugin. The JWKS is configured in x-custom-jwt.jku
See a jwt.io preview of a custom JWT crafted and signed by the plugin. If there is an “Invalid Signature” error (due probably to a JWKS download failure) put in jwt.io this public jwk content in the signature Public Key field.
x-custom-jwt plugin in KonnectKonnect is a hybrid architecture based on a Control Plane (for managing the configuration) and on Data Planes (aka the proxy gateway, for managing the API traffic) offering isolation for better security and performance.
Deploying a custom plugin requires updating the Control Plane and Data Planes:
Do a Git Clone of the repo:
1. Login to Konnect
2. Select your Gateway Manager
3. Click on Plugins
4. Click on + New Plugin
5. Click on Custom Plugins
6. Click on Create Custom Plugin
7. Click on Select file and open the schema.lua
8. Click on Save
1. See Data plane installation for Konnect documentation and select Docker
2. Update your docker container configuration with:
Mount definition (($(pwd) refers to kong-plugin-x-custom-jwt directory)
Environmental variable:
1. See Data plane installation for Konnect documentation and select Kubernetes
2. Create configMap
3. Add the following properties to the Helm values.yaml:
4. Execute the helm install:
In the rest of the document, we consider that the Kong Gateway is available at https://kong-gateway:8443. Please adapt this URL according to your environment.
1. Login to Konnect
2. Select the Gateway Manager
3. Create a Route to deliver the public JWKS (used by the backend API or jwt.io to verify the new JWT crafted by the plugin)
The Route has the following properties:
Add the Request Termination plugin to the x-custom-jwt-jwks Route with:
Add the CORS plugin to the x-custom-jwt-jwks Route with:
4. Create an httpbin Gateway Service for testing the plugin
Add a Gateway Service with:
Add a Route to the Service with:
Add Basic Authentication plugin to the basicAuth Route (Leave default parameters)
Add x-custom-jwt plugin to the httpbin Service with:
5. Create a Consumer with:
Open the Consumer and Go on Credentials / Basic Authentication, click on a + New Basic Auth Credential and put:
Request:
Response with x-custom-jwt header sent to the httpbin backend API:
1. Go on https://jwt.io
2. Copy/paste the x-custom-jwt header value
3. If everything works correctly the jwt.io sends a Signature Verified message. The public key is downloaded automatically through the /x-custom-jwt-jwks route and the Request Termination plugin. If that's not the case, open the Browser Developer Tools and see the network tab and console tab. Otherwise, put in jwt.io this jwk content in the signature Public Key field.
A common use case that is frequently requested is how to dynamically route requests based on authentication attributes. An example of this technique is routing requests to relevant upstream services based on claims contained in a JWT token. Admins w
Two of the best (in my opinion) features in Konnect are the ServiceHub and Dev Portal. However, they're also two of the most misunderstood. Aren't they the same thing? Why would you need a ServiceHub vs. Dev Portal? Well, I'm glad you asked! The r
Want to learn more about the nuts and bolts of APIOps? Download our eBook, Unlocking the Full Potential of your APIs with APIOps , and learn about the stages of APIOps, get an understanding of the technical assets required, and explore the tooling
As you build and maintain more applications, your authentication strategy becomes increasingly important. It may also be top of mind for your boss since technology leaders cited "improve application security" as one of their top priorities in this y
Kong Gateway is an API gateway and a core component of the Kong Konnect platform . Built on a plugin-based extensibility model, it centralizes essential functions such as proxying, routing, load balancing, and health checking, efficiently manag
"To prioritize the safety and security of the ecosystem, Kubernetes SIG Network and the Security Response Committee are announcing the upcoming retirement of Ingress NGINX . Best-effort maintenance will continue until March 2026. Afterward, there w