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.

• - [OIDC](https://docs.konghq.com/hub/kong-inc/openid-connect/)OIDC 
• - [JWT validation](https://docs.konghq.com/hub/kong-inc/jwt/)JWT validation
• - [Basic Authentication](https://docs.konghq.com/hub/kong-inc/basic-auth/)Basic Authentication
• - [Mutual TLS Authentication](https://docs.konghq.com/hub/kong-inc/mtls-auth/)Mutual TLS Authentication
• - [Key Authentication](https://docs.konghq.com/hub/kong-inc/key-auth/)Key Authentication

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](https://jwt.io/#id_token=eyJraWQiOiJrb25nIiwidHlwIjoiSldUIiwiYWxnIjoiUlMyNTYiLCJqa3UiOiJodHRwczovL2tvbmctZ2F0ZXdheTo4NDQzL3gtY3VzdG9tLWp3dC9qd2tzIn0.eyJhY3QiOnsiY2xpZW50X2lkIjoiY29udGFjdEBrb25naHEuY29tLUlEMSJ9LCJqdGkiOiJkNzMxNWU5YS1hYjJjLTRlOGMtYWRhOS0zYjEyYzNiNGYzZTQiLCJpc3MiOiJodHRwczovL2tvbmctZ2F0ZXdheTo4NDQzL3gtY3VzdG9tLWp3dCIsImF1ZCI6Imh0dHA6Ly9odHRwYmluLmFwaW0uZXUvYW55dGhpbmciLCJpYXQiOjE3MTI1OTY0OTMsImV4cCI6MTcxMjU5ODI5MywiY2xpZW50X2lkIjoiMDEyMzQ1QVpFUlRZISJ9.GxM-20uKCkkN06IVSLAyR97QsR2mpMXnaIZzvyuD_cQo5ETIw6Axkb0X8rmNtPONa27okdPB_xVV8XOHC2QSeF4p8h7LZzgZKUg1_7Ixjw4A0Xs5CrRk58aSxFP1EjBGGR7jL896sqtTjz2coJZ7q0ZTqcTG0VDvMCoxmVYa4G5XDm-zOABkFf-Cp4oWxMkFxF3b6m22rjQeI25_5NxJaNAJM6VFVBcmXF9wJTDiOie11eKScuYNRgoICp_XDgPpqLWET4DIPYYWCw_ZFG9vlckXBteTVdEZxvxLVvVtxcrANeDRN3RR0XcSByh5pOIa-2rsa7cUGEyGDVeS4pwIIQ)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](https://github.com/Kong/kong-plugin-x-custom-jwt/blob/main/test-keys/RS256-jwk-public.json)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](https://cloud.konghq.com)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](https://github.com/Kong/kong-plugin-x-custom-jwt/blob/main/kong/plugins/x-custom-jwt/schema.lua)schema.lua

**8.** Click on Save

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

**1.** See [Data plane installation](https://docs.konghq.com/konnect/gateway-manager/data-plane-nodes/)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](https://docs.konghq.com/konnect/gateway-manager/data-plane-nodes/)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](https://kong-gateway:8443)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](https://cloud.konghq.com)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:

• - config.status_code=200
• - config.content_type=application/json
• - config.body=copy/paste the content of [./test-keys/RS256-jwks-public.json](https://github.com/Kong/kong-plugin-x-custom-jwt/blob/main/test-keys/RS256-jwks-public.json)./test-keys/RS256-jwks-public.json
• - Click on Save

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:

• - name=httpbin
• - URL=[http://httpbin.apim.eu/anything](http://httpbin.apim.eu/anything)http://httpbin.apim.eu/anything
• - Click on Save

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:

• - config.iss=[https://kong-gateway:8443/x-custom-jwt](https://kong-gateway:8443/x-custom-jwt)https://kong-gateway:8443/x-custom-jwt 
• - config.jku=[https://kong-gateway:8443/x-custom-jwt/jwks](https://kong-gateway:8443/x-custom-jwt/jwks)https://kong-gateway:8443/x-custom-jwt/jwks (see step #3)
• - config.private_jwk=copy/paste the content of [./test-keys/RS256-jwk-private.json](https://github.com/Kong/kong-plugin-x-custom-jwt/blob/main/test-keys/RS256-jwk-private.json)./test-keys/RS256-jwk-private.json
• - config.verbose=true
• - Click on Save

**5. **Create a Consumer with:

• - Username=contact@konghq.com
• - Custom Id=[contact@konghq.com](mailto:contact@konghq.com)contact@konghq.com-ID1
• - Click on Save

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](https://jwt.io)https://jwt.io

**1. **Go on [https://jwt.io](https://jwt.io)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](https://github.com/Kong/kong-plugin-x-custom-jwt/blob/main/test-keys/RS256-jwk-public.json)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](https://github.com/Kong/kong-plugin-x-custom-jwt/tree/main?tab=readme-ov-file#example-1-authorization-bearer-input)here
• - Of course, this mechanism does not provide the capabilities of an OAuth 2 Server. However, in the repository ([here](https://github.com/Kong/kong-plugin-x-custom-jwt/tree/main?tab=readme-ov-file#check-the-jws-with-the-jwt-plugin-and-build-the-introspect-route)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