Blog
|
Engineering
June 18, 2024
5 min read

How to Craft and Sign a Custom JWT in Kong Konnect

Jerome Guillaume

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:

  • authentication, like SSO and avoid session management
  • authorization giving access to certain resources 
  • securely exchange information in a compact form

Here are the main use cases in which the Kong Gateway should craft and sign a custom JWT:

  • Due to legacy, some Consumers still use API Key or Basic Authentication. At the same time, the backend APIs (requested by those Consumers) can require a JWT as input to embrace new standards and have a higher level of security. So the plugin is used to convert the API Key or Basic authentication to a modern JWT token authentication
  • Do like a token exchange: get the Consumer JWT token and craft a new JWT that can then be used to access protected resources. This pattern can be used, for instance, for BFF (Backend for Frontend) and avoid using the same token throughout the call chain to transmit the identity of the caller

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 header

Overview of the plugin mechanism

We propose the x-custom-jwt custom plugin for covering the use cases mentioned above. The mechanism of the plugin is:

  1. Craft a custom JWT using the input Authentication properties
  2. Load the private JWK from the plugin's configuration and convert it into a PEM format
  3. Sign the JWT with the PEM string for building a JWS (RS256 algorithm)
  4. Add the custom JWT to an HTTP Request Header backend API

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: 

  • OIDC/JWT: client_id=clientId (default input claim and configurable)
  • Basic Auth: client_id=UserName
  • mTLS: client_id=subjectDN
  • Key Auth: client_id=ApiKey

The 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.

How to deploy the x-custom-jwt plugin in Konnect

Konnect 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: 

  • The Control Plane is updated by receiving the schema.lua which holds the schema of its configuration and defines rules on it so that the user can only enter valid configuration values
  • The Data Planes need to be updated with the new custom plugin logic that we have defined. We can do this either by creating a custom image in Docker with our code or creating a configmap in the Kubernetes cluster and pointing Kong to that configmap on startup

Prerequisite

Do a Git Clone of the repo:

git clone https://github.com/Kong/kong-plugin-x-custom-jwt

Deploy the plugin schema in Konnect (Control Plane)

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

Deploy the plugin in Kong Gateway (Data Plane) | Docker

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)

--mount type=bind,source="$(pwd)"/kong/plugins/x-custom-jwt,destination=/usr/local/share/lua/5.1/kong/plugins/x-custom-jwt

Environmental variable:

KONG_PLUGINS=bundled,x-custom-jwt

Deploy the plugin in Kong Gateway (Data Plane) | Kubernetes

1. See Data plane installation for Konnect documentation and select Kubernetes

2. Create configMap

cd ./kong-plugin-x-custom-jwt/kong/plugins
kubectl -n kong create configmap x-custom-jwt --from-file=./x-custom-jwt

3. Add the following properties to the Helm values.yaml:

image:
  repository: kong/kong-gateway
  ...
env:
...
plugins:
  configMaps:
  - pluginName: x-custom-jwt
    name: x-custom-jwt

4. Execute the helm install:

helm install my-kong kong/kong -n kong --values ./values.yaml

How to test the plugin

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.

Configuration of the Gateway Service, the Routes, and the plugins

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:

  • name=x-custom-jwt-jwks
  • path=/x-custom-jwt/jwks
  • Click on Save

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:

  • config.origins=*
  • Click on Save

4. Create an httpbin Gateway Service for testing the plugin

Add a Gateway Service with:

Add a Route to the Service with:

  • name=basicAuth
  • path=/basicAuth
  • Click on Save

Add Basic Authentication plugin to the basicAuth Route (Leave default parameters)

  • Click on Save

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:

  • username=my-user
  • password=My p@ssword!
  • Click on Save

Test the plugin and craft your custom JWT

Request:

curl -k -u 'my-user:My p@ssword!' https://kong-gateway:8443/basicAuth

Response with x-custom-jwt header sent to the httpbin backend API:

HTTP/1.1 200 OK
..
Via: kong/3.6.1.1-enterprise-edition

{
    ...
    "headers": {
        "Authorization": "Basic bXktdXNlcjpNeSBwQHNzd29yZCE=",
        "Host": "httpbin.apim.eu",
        "X-Custom-Jwt": "eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8va29uZy1nYXRld2F5Ojg0NDMveC1jdXN0b20tand0L2p3a3MiLCJ0eXAiOiJKV1QiLCJraWQiOiJrb25nIn0.eyJjbGllbnRfaWQiOiJteS11c2VyIiwiaWF0IjoxNzEyNzY3MTM2LCJhY3QiOnsiY2xpZW50X2lkIjoiY29udGFjdEBrb25naHEuY29tLUlEMSJ9LCJqdGkiOiI5MjAyNjhmOC05MzFlLTRkMjYtODUyMi1jNmJhMGJhMjkzY2IiLCJleHAiOjE3MTI3Njg5MzYsImlzcyI6Imh0dHBzOi8va29uZy1nYXRld2F5Ojg0NDMveC1jdXN0b20tand0IiwiYXVkIjoiaHR0cDovL2h0dHBiaW4uYXBpbS5ldS9hbnl0aGluZyJ9.N0g0hkUCbFuaccJS32TQJI02wIbMwC1Qj8UnaVbYahokfCulGZkPP9rwmSy73PYJM2vab6PLoqeKQ7XqUIUtIMSuvNS4W6fcEO1ilVt_2LQyqYFR3NDIRLjVf3_LyGWcExsxceon-8LGfrZN817GlLG5XbHzIXZXPDsdiAca_nnZgFaWK7BChF4IOpym7clHD4c6Uh0XDLEkgLzinZLRGm-PTy4REKq7yF3V913aMrS-gMaSDJbpGk6TWGEKERKoyGxvN8y2vH0y-6TA-XVWUM8U3Vdg-wjczlEbMXmlvFdVc2hRAsrjgb19vph4LH2NkvauZdBsP7UBXhz2dKWNkw",
        ...
    },
    ...
    "url": "https://kong-gateway/anything"
}

Check the custom JWT with https://jwt.io

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.

What’s next?

  • Other use cases, involving different Kong’s security plugins, like OIDC, mTLS, and Api Key, are available here
  • Of course, this mechanism does not provide the capabilities of an OAuth 2 Server. However, in the repository (here) we explain how to easily configure an /introspection endpoint by using the JWT plugin. It offers a way to check the JWT (signature, expiration and the credential) for the backend APIs.
  • Feel free to adapt the code of the x-custom-jwt to include the claims you need
  • As a good practice, please apply rotation key
Jerome Guillaume

Recommended posts

Dynamic Routing Based on JWT Token’s Claim with Kong Konnect

Engineering

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

Shlomi Tubul

Kong-plement Your ServiceHub With a Dev Portal

Engineering

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

Michael Heap

Automating Your Developer Pipeline With APIOps (DevOps + GitOps)

Engineering

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

Ross McDonald

How JWT Authentication Works for Microservices: API Gateway Tutorial

Engineering

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

Marco Palladino

Configuring Kong Dedicated Cloud Gateways with Managed Redis in a Multi-Cloud Environment

Engineering

Architecture Overview A multicloud DCGW architecture typically contains three main layers. 1\. Konnect Control Plane The SaaS control plane manages configuration, plugins, and policies. All gateways connect securely to this layer. 2\. Dedicated C

Hugo Guerrero

Leveraging the MCP Registry in Kong Konnect for Dynamic Tool Discovery

Engineering

Tool discovery for AI agents In early agent implementations, tools are often statically configured inside the agent. For example: { "mcpServers": { "weatherServer": { "command": "uv", "args": "run", "weather_serv

Hugo Guerrero

Secure AI at Scale: Prisma AIRS and Kong AI Gateway Now Integrated

Engineering

In today's digital landscape, APIs are the backbone of modern applications, and AI is the engine of innovation. As organizations increasingly rely on microservices and AI-powered features, the API gateway has become the critical control point for man

Tom Prenderville

Ready to see Kong in action?

Get a personalized walkthrough of Kong's platform tailored to your architecture, use cases, and scale requirements.

Get a Demo