This plugin will add a signed JWT into the HTTP Header JWT of proxied requests through the Kong gateway. The purpose of this, is to provide means of Authentication, Authorization and Non-Repudiation to API providers (APIs for which Kong is a gateway).

API Providers need a means of cryptographically validating that requests they receive were proxied by Kong and not tampered with during transmission from Kong -> API Provider. This token accomplishes both as follows:

  1. Authentication & Authorization - Provided by means of JWT signature validation. The API Provider will validate the signature on the JWT token (which is generating using Kong’s RSA x509 private key), using Kong’s public key. This public key can be maintained in a keystore, or sent with the token - provided API providers validate the signature chain against their truststore.

  2. Non-Repudiation - SHA256 is used to hash the body of the HTTP request body, and the resulting digest is included in the payloadhash element of the JWT body. API Providers will take the SHA256 hash of the HTTP Request Body, and compare the digest to that found in the JWT. If they are identical, the request remained intact during transmission.


Terminology

  • plugin: a plugin executing actions inside Kong before or after a request has been proxied to the upstream API.
  • Service: the Kong entity representing an external upstream API or microservice.
  • Route: the Kong entity representing a way to map downstream requests to upstream services.
  • upstream service: this refers to your own API/service sitting behind Kong, to which client requests are forwarded.
  • API: a legacy entity used to represent your upstream services. Deprecated in favor of Services since CE 0.13.0 and EE 0.32.

Configuration

Enabling the plugin on a Service

Configure this plugin on a Service by making the following request:

$ curl -X POST http://kong:8001/services/{service}/plugins \
    --data "name=kong-upstream-jwt" 

  • service: the id or name of the Service that this plugin configuration will target.

Enabling the plugin on a Route

Configure this plugin on a Route with:

$ curl -X POST http://kong:8001/routes/{route_id}/plugins \
    --data "name=kong-upstream-jwt" 

  • route_id: the id of the Route that this plugin configuration will target.

Enabling the plugin on an API

If you are using an older version of Kong with the legacy API entity (deprecated in favor of Services since CE 0.13.0 and EE 0.32.), you can configure this plugin on top of such an API by making the following request:

$ curl -X POST http://kong:8001/apis/{api}/plugins \
    --data "name=kong-upstream-jwt" 

  • api: either id or name of the API that this plugin configuration will target.

Global plugins

All plugins can be configured using the http://kong:8001/plugins/ endpoint. A plugin which is not associated to any Service, Route or Consumer (or API, if you are using an older version of Kong) is considered "global", and will be run on every request. Read the Plugin Reference and the Plugin Precedence sections for more information.

Parameters

Here's a list of all the parameters which can be used in this plugin's configuration:

form parameterdefaultdescription
nameThe name of the plugin to use, in this case kong-upstream-jwt
service_idThe id of the Service which this plugin will target.
route_idThe id of the Route which this plugin will target.
enabledtrueWhether this plugin will be applied.
api_idThe id of the API which this plugin will target. Note: The API Entity is deprecated in favor of Services since CE 0.13.0 and EE 0.32.

Installation

Recommended:

$ luarocks install kong-upstream-jwt

Other:

$ git clone https://github.com/Optum/kong-upstream-jwt.git /path/to/kong/plugins/kong-upstream-jwt
$ cd /path/to/kong/plugins/kong-upstream-jwt
$ luarocks make *.rockspec

Configuration

The plugin requires that Kong’s private key be accessible in order to sign the JWT. We also include the x509 cert in the x5c JWT Header for use by API providers to validate the JWT. We access these via Kong’s overriding environment variables KONG_SSL_CERT_KEY for the private key as well as KONG_SSL_CERT_DER for the public key. The first contains the path to your .key file, the second specifies the path to your public key in DER format .cer file.

If not already set, these can be done so as follows:

$ export KONG_SSL_CERT_KEY="/path/to/kong/ssl/privatekey.key"
$ export KONG_SSL_CERT_DER="/path/to/kong/ssl/kongpublickey.cer"

One last step is to make the environment variables accessible by a nginx worker. To do this, simply add these line to your nginx.conf

env KONG_SSL_CERT_KEY;
env KONG_SSL_CERT_DER;

Maintainers

jeremyjpj0916
rsbrisci

Feel free to open issues, or refer to our Contribution Guidelines if you have any questions.