Skip to content

Latest commit

 

History

History
110 lines (79 loc) · 4.42 KB

README.md

File metadata and controls

110 lines (79 loc) · 4.42 KB
Raw

Kong Plugin - JWT Crafter for Kong Enterprise Edition

Luarocks

This plugin adds the possibility to generate a JWT token within Kong itself, eliminating the need for a upstream service doing the token generation.

The JWT plugin included in Kong has two main features: storing JWT secrets per consumer and verifying tokens when proxying to upstream services. It is missing the capability to generate a token based on successful authentication.

This plugin needs two other plugins to work:

  • the JWT plugin itself, it uses it to fetch the JWT credential where the consumer's signing secret is stored
  • any authentication plugin (e.g. Basic authentication, JWT, OAuth2); a consumer must be authenticated to generate a token

It also uses the ACL plugin and embeds all the consumer ACLs inside the token claims section. Upstream services can then decode the token and use the ACLs from the token to authorize users within app code.

Kong Compatibility

This plugin has only been tested with Kong Enterprise version 0.34-1. This plugin has not been tested with Kong OSS.

Example

Create an API and a consumer with a JWT credential (not token), add Basic auth to the API:

# Create sign in API
curl -XPOST -H 'Content-Type: application/json' -d '{"uris": "/sign_in", "upstream_url": "http://localhost", "name": "sign_in_api"}' localhost:8001/apis

# Create consumer
curl -XPOST -H 'Content-Type: application/json' -d '{"username": "test"}' localhost:8001/consumers

# Create JWT credential for consumer
curl -XPOST -H 'Content-Type: application/json' localhost:8001/consumers/{consumer_id_from_above}/jwt

# Create basic auth credentials for consumer
curl -XPOST -d 'username=user' -d 'password=pass' localhost:8001/consumers/{consumer_id_from_above}/basic-auth

# Enable basic auth for sign in API
curl -XPOST -d 'name=basic-auth' localhost:8001/apis/{api_id_from_above}/plugins

Note: the upstream_url of the API is irrelevant, the plugin short circuits the response and returns the token directly from Kong. Just make sure to enter a URL which can resolve on DNS, otherwise Kong complains. This is a known limitation of Kong.

Enable the JWT crafter plug-in:

curl -X POST -d 'name=jwt-crafter' localhost:8001/apis/{api_id_from_above}/plugins

Putting it all together, calling the created API authenticated using Basic authentication will yield the following response:

# user:pass is base64 encoded
curl -H 'Authorization: basic dGVzdDp0ZXN0' localhost:8000/sign_in
{
  "token_type": "Bearer",
  "expires_in": 28800,
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW0iOiJ0ZXN0Iiwic3ViIjoiYzNiODMzMDgtMWYyNS00M2VmLWExN2MtOWNjNTBlOGI3OWQ2IiwiaXNzIjoiNmIzOWYzNzhjNzQzNGUyMmIzZjg4N2Q2ZTMzNDgwOTkiLCJleHAiOjE0OTU5MTAwODMsInJvbCI6WyJhYWEiLCJiYmIiXX0.yMufTuFi7aKpJeDYGiiR0en035w3G_MNHtQO4xkIKdU"
}

Decoded token:

{
  "alg": "HS256",
  "typ": "JWT"
}
{
  "nam": "test", // Credential username or user ID
  "sub": "c3b83308-1f25-43ef-a17c-9cc50e8b79d6", // Consumer ID
  "iss": "6b39f378c7434e22b3f887d6e3348099", // JWT credential key (issuer)
  "exp": 1495910051, // Valid until
  "rol": [ // ACLs of the consumer from Kong
    "aaa",
    "bbb"
  ]
}

Installation on Kong Enterprise

Verify that you have git installed on your Kong host or container. For the Kong Docker image on Alpine, run the following Alpine install command:

apk add --no-cache git

Install the rock when building your Kong image/instance:

luarocks install kong-plugin-jwt-crafter-for-ee

Add the plugin to your custom_plugins section in kong.conf, or the KONG_CUSTOM_PLUGINS environment variable.

custom_plugins = jwt-crafter

Please note: If installing on a Docker container, it is advised to install the rock on the container first, and then image that container. Use the new image with the KONG_CUSTOM_PLUGINS environment variable during startup.

Configuration

All configuration options are optional

key default value description
expires_in 8 * 60 * 60 validity of token in seconds

Limitations

Currently, the plugin loads the first HS256 JWT credential of the consumer. It does not include other signing algorithms or a possibility to specify which consumer JWT credential should be used to sign the key if the consumer has multiple credentials.