JWT Signer

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.

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

• Signature verification requires config.access_token_jwks_uri and/or config.channel_token_jwks_uri.

• Introspection requires introspection endpoints config.access_token_introspection_endpoint and/or config.channel_token_introspection_endpoint.

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.

The following parameters let you map Consumers:

• config.access_token_consumer_claim
• config.access_token_introspection_consumer_claim
• config.channel_token_consumer_claim
• config.channel_token_introspection_consumer_claim

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.

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.

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.

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.