Related Documentation
Made by
Kong Inc.
Incompatible with
konnect
Supported Gateway Topologies
hybrid db-less traditional
Compatible Protocols
grpc grpcs http https

The Kong Gateway JWT Signer plugin allows you to verify, sign, or re-sign one or two tokens in a request. With a two-token request, one token is allocated to an end user and the other token to the client application, for example.

The plugin refers to tokens as an access token and channel token. Tokens can be any valid verifiable tokens. The plugin supports both opaque tokens through introspection, and signed JWT tokens through signature verification. There are many configuration parameters available to accommodate your requirements.

Configuration notes

Most of the plugin’s configuration parameters are optional, but you need to specify some options to actually make the plugin work:

Manage key signing

If you specify config.access_token_keyset or config.channel_token_keyset with either an http:// or https:// prefix, it means that token signing keys are externally managed by you. In that case, the plugin loads the keys just like it does for config.access_token_jwks_uri and config.channel_token_jwks_uri. If the prefix is not http:// or https:// (such as "my-company" or "kong"), Kong Gateway autogenerates JWKS for supported algorithms.

External JWKS specified with config.access_token_keyset or config.channel_token_keyset should also contain private keys with supported alg, either "RS256" or "RS512" for now. External URLs that contain private keys should be protected so that only Kong Gateway can access them. Currently, Kong Gateway doesn’t add any authentication headers when it loads the keys from an external endpoint, so you have to do it with network level restrictions. If you commonly need to manage private keys externally instead of allowing Kong Gateway to autogenerate them, you can add another parameter for adding an authentication header (possibly similar to config.channel_token_introspection_authorization).

The key size (the modulo) for RSA keys is currently hard-coded to 2048 bits.

Consumer mapping

The following parameters let you map Consumers:

The plugin only maps Consumers once.

It applies mappings in the following order, depending on whether the input is opaque or JWT:

  1. Access token introspection results
  2. Access token JWT payload
  3. Channel token introspection results
  4. Channel token JWT payload

When mapping is done, no other mappings are used. The plugin won’t try to remap or override Consumers once they’ve been found and mapped. For example, if an access token already maps to a Kong Gateway Consumer, the plugin doesn’t try to map a channel token to that Consumer anymore, and won’t throw any errors.

A general rule is to map either the access token or the channel token, not both.

Cached JWKS

The plugin caches JWKS specified with config.access_token_jwks_uri and config.channel_token_jwks_uri to the Kong Gateway database for quicker access to them. The plugin further caches JWKS in Kong Gateway nodes’ shared memory, and on a per-process level in memory for even quicker access. When the plugin is responsible for signing the tokens, it also stores its own keys in the database.

Admin API endpoints never reveal private keys, but do reveal public keys. Private keys that the plugin autogenerates can only be accessed from the database directly. Private parts in JWKS include properties such as d, p, q, dp, dq, qi, and oth.

For public keys using a symmetric algorithm (such as HS256) that include the k parameter, the parameter isn’t hidden from the Admin API because it is used both to verify and to sign. This makes it a bit problematic to use, and we strongly suggest using asymmetric (or public key) algorithms. Doing so also makes rotating the keys easier because the public keys can be shared between parties and published without revealing their secrets.

Allow your upstream service to verify Kong Gateway-issued tokens

You can give your upstream service the /jwt-signer/jwks/kong URL for it to verify Kong Gateway-issued tokens. The response is a standard JWKS endpoint response.

The kong suffix in the URI is a default value. You can change it with config.access_token_issuer or config.channel_token_issuer.

You can also make a loopback to this endpoint by routing the Kong Gateway proxy to this URL. Then, you can use an authentication plugin to protect access to this endpoint, if needed.

The JWT Signer plugin automatically reloads or regenerates missing JWKS if it can’t find cached ones. The plugin also tries to reload JWKS if it can’t verify the signature of the original access token or channel token, such as when the original issuer has rotated its keys and signed with the new one that is not found in Kong Gateway cache.

Rotate signing token Keys

Sometimes you might want to rotate the Keys Kong Gateway uses for signing tokens specified in config.access_token_keyset and config.channel_token_keyset, or reload tokens specified in config.access_token_jwks_uri and config.channel_token_jwks_uri.

Kong Gateway stores and uses at most two set of Keys: current and previous. If you want Kong Gateway to forget the previous Keys, you need to rotate Keys twice, as it effectively replaces both current and previous Key Sets with newly generated tokens or reloaded tokens if the Keys were loaded from an external URI.

Something wrong?

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!