Community Plugin: This plugin is developed, tested, and maintained by a third-party contributor.
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:
-
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.
-
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.
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.
Configuration Reference
This plugin is compatible with DB-less mode.
Example plugin configuration
Enable on a service
Enable on a route
Enable globally
The following examples provide some typical configurations for enabling
the kong-upstream-jwt
plugin on a
service.
Admin API
Kubernetes
Declarative (YAML)
Make the following request:
curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
--data "name=kong-upstream-jwt"
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: kong-upstream-jwt-example
config:
EXAMPLE_PARAMETER: EXAMPLE_VALUE
plugin: kong-upstream-jwt
Next, apply the KongPlugin resource to a
service by annotating the
service as follows:
apiVersion: v1
kind: Service
metadata:
name: SERVICE_NAME|SERVICE_ID
labels:
app: SERVICE_NAME|SERVICE_ID
annotations:
konghq.com/plugins: kong-upstream-jwt-example
spec:
ports:
- port: 80
targetPort: 80
protocol: TCP
name: SERVICE_NAME|SERVICE_ID
selector:
app: SERVICE_NAME|SERVICE_ID
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
Add this section to your declarative configuration file:
plugins:
- name: kong-upstream-jwt
service: SERVICE_NAME|SERVICE_ID
config:
EXAMPLE_PARAMETER: EXAMPLE_VALUE
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
The following examples provide some typical configurations for enabling
the kong-upstream-jwt
plugin on a
route.
Admin API
Kubernetes
Declarative (YAML)
Make the following request:
curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
--data "name=kong-upstream-jwt"
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration will target.
First, create a KongPlugin
resource:
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
name: kong-upstream-jwt-example
config:
EXAMPLE_PARAMETER: EXAMPLE_VALUE
plugin: kong-upstream-jwt
Then, apply it to an ingress (route or routes)
by annotating the ingress as follows:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ROUTE_NAME|ROUTE_ID
annotations:
kubernetes.io/ingress.class: kong
konghq.com/plugins: kong-upstream-jwt-example
spec:
rules:
- host: examplehostname.com
http:
paths:
- path: /bar
backend:
service:
name: echo
port:
number: 80
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration will target.
Note: The KongPlugin resource only needs to be defined once
and can be applied to any service, consumer, or route in the namespace. If you
want the plugin to be available cluster-wide, create the resource as a
KongClusterPlugin
instead of KongPlugin
.
Add this section to your declarative configuration file:
plugins:
- name: kong-upstream-jwt
route: ROUTE_NAME
config:
EXAMPLE_PARAMETER: EXAMPLE_VALUE
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration
will target.
A plugin which is not associated to any service, route, or consumer is
considered global, and will be run on every request. Read the
Plugin Reference and the Plugin Precedence
sections for more information.
The following examples provide some typical configurations for enabling
the kong-upstream-jwt
plugin globally.
Admin API
Kubernetes
Declarative (YAML)
Make the following request:
curl -X POST http://localhost:8001/plugins/ \
--data "name=kong-upstream-jwt"
Create a KongClusterPlugin
resource and label it as global:
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: <global-kong-upstream-jwt>
annotations:
kubernetes.io/ingress.class: kong
labels:
global: \"true\"
config:
<optional_parameter>: <value>
plugin: kong-upstream-jwt
Add a plugins
entry in the declarative
configuration file:
plugins:
- name: kong-upstream-jwt
config:
EXAMPLE_PARAMETER: EXAMPLE_VALUE
Parameters
Here's a list of all the parameters which can be used in this plugin's configuration:
Form Parameter |
Description |
name
required
Type: string
|
The name of the plugin, in this case kong-upstream-jwt . |
instance_name
optional
Type: string
|
An optional custom name to identify an instance of the plugin, for example kong-upstream-jwt_my-service .
Useful when running the same plugin in multiple contexts, for example, on multiple services.
|
service.name or service.id
optional
Type: string
|
The name or ID of the service the plugin targets.
Set one of these parameters if adding the plugin to a service through the top-level /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
optional
Type: string
|
The name or ID of the route the plugin targets.
Set one of these parameters if adding the plugin to a route through the top-level /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
enabled
optional
Type: boolean
Default value: true
|
Whether this plugin will be applied. |
api_id
Type: string |
The ID of the API the plugin targets.
Note: The API Entity is deprecated in favor of Services since CE 0.13.0 and EE 0.32. |