Kong Upstream JWT

The Kong Upstream JWT plugin adds a signed JWT into the HTTP Header JWT of requests proxied through Kong Gateway. This provides a means of authentication, authorization, and non-repudiation to upstream services.

Upstream services need a means of cryptographically validating that requests they receive were proxied by Kong Gateway and not tampered with during transmission. JWT validation accomplishes both as follows:

1. Authentication & Authorization: Provided by means of JWT signature validation. The JWT token is generated using Kong Gateway’s RSA x509 private key. Upstream services will then validate the signature of the generated JWT token using Kong Gateway’s public key. This public key can be maintained in a keystore, or sent with the token, provided that upstream services 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. Upstream services will take the SHA256 hash of the HTTP request body and compare the digest to that found in the JWT. If the digests are identical, they can be certain that the request remained intact during transmission.

The plugin requires Kong Gateway’s private key is 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 Gateway’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:

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

Make the environment variables accessible by a Nginx worker by adding these lines to your nginx.conf:

env KONG_SSL_CERT_KEY;
env KONG_SSL_CERT_DER;

You can install the Kong Upstream JWT plugin via LuaRocks. A Lua plugin is distributed in .rock format, which is a self-contained package that can be installed locally or from a remote server.

1. Install the Kong Upstream JWT plugin:

   luarocks install kong-upstream-jwt
   

2. Update your loaded plugins list in Kong Gateway.

   In your kong.conf, append kong-upstream-jwt to the plugins field. Make sure the field isn’t commented out.

   plugins = bundled,kong-upstream-jwt
   

3. Restart Kong Gateway:

   kong restart