Careful! You are browsing documentation for an outdated version of Kong. Go here to browse the documentation for the latest version.

Installing a Plugin

One of Kong's core principle is its extensibility through Plugins, which allow you to add features to your APIs.

Let's configure the Key Authentication plugin to add a simple key authentication to the API.

1. Enabling the Plugin

We need to make sure that the plugin name is in the plugins_available property of your node's configuration:

plugins_available:
  - keyauth

This will make Kong load the plugin. When changing the configuration file, we need to restart Kong:

$ kong restart

Repeat this step for every node in your cluster.

2. Configuring the Plugin

To enable the plugin on the API, we need to retrieve the API id that has been created when we added the API on Kong. We can list all of the APIs configured on Kong by executing:

$ curl http://127.0.0.1:8001/apis/

Once we have got the id of the API, we can configure the key authentication plugin by performing a POST request with the following parameters:

  • name: name of the Plugin
  • api_id: id of the API the plugin will be added to
  • value.key_names: value is a property that is being shared by every plugin, and it is where their configuration is being set. As documented in the Plugin's Profile, key_names is a comma-separated string array that represents the key names, header names or JSON property names where Kong will look for a credential.

We would like every API consumer to send their credential in an apikey field, so we would configure the Plugin like this:

$ curl -i -X POST \
  --url http://127.0.0.1:8001/plugins_configurations/ \
  --data 'name=keyauth&api_id=<api_id>&value.key_names=apikey'

HTTP/1.1 201 Created
...
{
  "api_id": "<api_id>",
  "value": { 
    "key_names": ["apikey"], 
    "hide_credentials":vfalse 
  },
  "id": "<id>",
  "enabled": true,
  "name": "keyauth"
}

Here we go, the Plugin has been successfully configured and enabled.

If we now try to make an HTTP request to the same API, Kong will tell us that we are not authenticated to make the request.

$ curl -i -X GET \
  --url http://127.0.0.1:8000/ \
  --header 'Host: api.mockbin.com'

  HTTP/1.1 403 Forbidden
  ...
  {
    "message": "Your authentication credentials are invalid" 
  }

That happened because the request we made didn't provide a key named apikey (as specified by our plugin configuration) and it has been blocked by Kong. The request never reached the final API.

To authenticate against the API, we need to pass a credential along with the request. As documented in the Plugin's Usage, we need to create a Consumer and a credential key:

$ curl -i -X POST \
  --url http://127.0.0.1:8001/consumers/ \
  --data 'username=tutorial_user'

HTTP/1.1 201 Created

# Make sure the given consumer_id matches the freshly created account:
$ curl -i -X POST \
  --url http://127.0.0.1:8001/keyauth_credentials/
  --data 'key=123456&consumer_id=<consumer_id>'
HTTP/1.1 201 Created

That consumer with an associated 123456 key credential can now consume the API. We can retry to make the request passing the proper value into an apikey parameter:

$ curl -i -X GET \
  --url http://127.0.0.1:8000/?apikey=123456 \
  --header 'Host: api.mockbin.com'

HTTP/1.1 200 OK

Success! The request was proxied successfully to the final API.

To go further into mastering Kong and its plugins, refer to the complete documentation, and read carefully each plugin's instruction in the Plugins Gallery.