Kong JWT Claims Forwarder Plugin

A custom Kong Gateway plugin that extracts specified claims from a validated JWT and forwards them as HTTP request headers to upstream services.

Installation

For detailed instructions on installing custom plugins, please refer to the official Kong documentation

Deploying Custom Plugins

Configuration

The plugin is configured on a Service or Route in your kong.yaml file. Here is a breakdown of the configuration options:

Parameter	Default	Description
config.claims_to_forward	[]	An array of objects, where each object defines a mapping from a JWT claim to an HTTP header.
claim_name	(required)	The name of the claim to extract from the JWT payload (e.g., sub, scope).
header_name	(required)	The name of the HTTP header to create (e.g., X-User-ID).
always_set_header	true	A boolean. If true, the header will be set with an empty value even if the claim is missing or empty. If false, the header will only be added if the claim exists and has a value.
decoded_token_context_key	authenticated_jwt_token	The key in kong.ctx.shared where the plugin will look for the raw JWT string. This allows compatibility with other auth plugins.

Example Usage

This example shows a full Plugin Chain where our plugin is used to enable per-user rate limiting.

services:
  - name: my-api-service
    url: http://my-upstream-api
    plugins:
      # Step 1: The official JWT plugin validates the incoming token.
      - name: jwt
        config:
          key_claim_name: "iss"

      # Step 2: Our custom plugin extracts the user ID after validation.
      - name: jwt-claims-forwarder
        config:
          claims_to_forward:
            - claim_name: sub
              header_name: X-User-ID
            - claim_name: scope
              header_name: X-User-Scopes
              # We don't want to set this header empty if the scope is missing.
              always_set_header: false

      # Step 3: The rate-limiting plugin uses the header created by our plugin.
      - name: rate-limiting
        config:
          minute: 100
          limit_by: header
          header_name: X-User-ID

License

This project is licensed under the MIT License. See the MIT license file for details.