November 3, 2022
5 min read

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

Shlomi Tubul

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 would like all their clients to go to the same URI as it makes the implementation easier. But behind the scenes they might need to tailor specific configuration/applications for them, hence routing their request based on their identity.

Kong Gateway is typically ran with a set of ancillary services, including a backend datastore, Kong Manager, Analytics, and Developer Portal. Traditionally, users of Kong Gateway have been required to self host these additional services to experience the full capabilities of the Kong platform.

In this post, we’ll use Kong Konnect, the new Kong SaaS API platform. Konnect hosts the Kong platform’s management capabilities (backend datastore, Kong Manager, Analytics, Developer Portal, and more) in a multi-cloud environment. This frees the customer from managing these ancillary services and allows them to focus on hosting the data planes (aka, proxy runtimes) and building their business logic.

As we’ve seen in a previous blog post, Kong thrives in routing requests dynamically. However, in this post, we’ll take things a step further by dynamically routing requests based on the authentication process.

While we’re going to be covering everything using Konnect, it’s important to highlight that you can use the same procedure below in your own self-managed environment, as the same configuration applies to all deployments.

To start, let’s outline the prerequisites:

  1. A Konnect account and a connected runtime. This is documented in the Get started with Konnect page, steps 1 and 2.
  2. A Konnect personal access token (PAT). To generate the token, log in to your account, click on your username, then “Personal access token”, then press the “Generate token” button. (See figure 1 below.)
  3. decK, installed locally, decK is a tool used to declaratively configure Kong Gateway. Using decK with Kong Konnect contains the instructions for connecting your local decK installation to your Konnect account.
  4. 3rd party Identity Provider (IdP). For this demo, I am using Keycloak. I’ve set up two users that will access the "/bank" route in our proxy port. The user bob will use the "great-discount" bank and suzy will use the "low-interest" bank. This off course can be implemented with any Identity provider support oauth2 you are using.

Figure 1

High Level Architecture

For our example use case, we are managing a banking application that serves different bank's customers.

In my example , all customers go to the same service address ( which is basically a DNS entry where the Kong service resides. Within Kong we will have the following configured:

  • A service — A representation of our application
  • A route — A route will let you expose how a service is being requested.

During our demo, we will show how we can route 2 requests that sent to the same route to 2 different paths based on authentication properties.

For our use case, we will use the authentication mechanism to determine which path needs to be used, based on the JWT claims of the authenticated user. The claim we’ll use will be labeled “bank”. An architectural diagram of the scenario is shown below:

Here is an example of a JWT token. The “bank” attribute contains the information we will use to route the request.


To make things easier to identify, we’ll create a simple web application that will just print the path of the requested URL. This will allow us to see where exactly the user has been redirected.

To make things as simple as possible, we’ll use a simple python script that creates a web server and prints the path. This python script is shown below:

To test our app , we can just run it:

Once the app is running, we can look at our browser (with the address of the local server) to see how it works:

So as we haven’t put our application behind Kong and the OIDC authentication, there is no bank name yet.

Implement configuration to Kong GW

To bulk load the Kong configuration, we will use a tool called decK, which will enable us to configure our complete setup with just one call.

For our use case, the declarative file (demo-deployment.yaml) looks as follows:

There are a couple of notes to highlight from our YAML file:

  • We created a service named "bank-demo service" which basically represents our backend application which is the simple python application.
  • We created a route with the path /bank to allow access to the service.
  • We attached the openid-connect plugin to the bank service. The plugin is configured to integrate with a keycloak demo instance. We have also transformed the "bank" claim in the JWT token to a header attribute, for routing purposes.
  • We attached the request-transformer-advanced plugin to replace the backend url with a new one that consists with the value of the "bank" header.\

To completely configure the gateway, we need one simple decK command:

For additional info on how to use decK with our Konnect Cloud offer, you can follow Kong's official documentation.

If we want to take a look on how this implementation looks in konnect UI:

Now, let’s test our application.

When we try to access our service through the runtime instance (in my case running locally on my laptop), we are redirected to keycloak for authentication. The first user we will try is Bob:

And the result is:

Now lets try with our other user, Suzy:

And the result is similar, but we are redirected to a new URL, as it was expected:


In this blog, we saw how easy it is to leverage Kong in order to create complex dynamic routing based on specific attributes (in this case, JWT token's claims).

All users have the same Login process, and according to their attributes they are routed to the relevant application/path for their service. This makes the maintenance of the deployed application much easier and cleaner.

In this demo, we used Kong’s Konnect (SaaS) which makes deployment and maintenance much easier. As Kong can be deployed in the vast majority of architectures (on-prem, cloud, hybrid, docker, k8s, etc), you can reproduce these capabilities no matter which form you choose.

Ready to try Kong Konnect?

Accelerate your journey to microservices, secure and govern APIs and services, and boost developer productivity with Kong Konnect, the easiest way to get started with Kong Enterprise

Start a Free Trial >

Developer agility meets compliance and security. Discover how Kong can help you become an API-first company.