Add Key Authentication (also sometimes referred to as an API key) to a Service or a Route (or the deprecated API entity). Consumers then add their key either in a querystring parameter or a header to authenticate their requests.
Configuration Reference
Example plugin configuration
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 key-auth . |
service.name or service.id
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
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
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. |
config.key_names
optional Default value: apikey
|
Describes an array of comma separated parameter names where the plugin will look for a key. The client must send the authentication key in one of those key names, and the plugin will try to read the credential from a header or the querystring parameter with the same name. |
config.key_in_body
optional Default value: false
|
If enabled, the plugin will read the request body (if said request has one and its MIME type is supported) and try to find the key in it. Supported MIME types are |
config.hide_credentials
optional Default value: false
|
An optional boolean value telling the plugin to show or hide the credential from the upstream service. If |
config.anonymous
optional |
An optional string (consumer uuid) value to use as an “anonymous” consumer if authentication fails. If empty (default), the request will fail with an authentication failure |
config.run_on_preflight
optional Default value: true
|
A boolean value that indicates whether the plugin should run (and try to authenticate) on |
Note that, according to their respective specifications, HTTP header names are treated as case insensitive, while HTTP query string parameter names are treated as case sensitive. Kong follows these specifications as designed, meaning that the key_names
configuration values will be treated differently when searching the request header fields, versus searching the query string. Administrators are advised against defining case-sensitive key_names
values when expecting the authorization keys to be sent in the request headers.
Once applied, any user with a valid credential can access the Service/API. To restrict usage to only some of the authenticated users, also add the ACL plugin (not covered here) and create whitelist or blacklist groups of users.
Usage
In order to use the plugin, you first need to create a Consumer to associate one or more credentials to. The Consumer represents a developer using the upstream service.
Create a Consumer
You need to associate a credential to an existing Consumer object. To create a Consumer, you can execute the following request:
$ curl -X POST http://kong:8001/consumers/ \
--data "username=<USERNAME>" \
--data "custom_id=<CUSTOM_ID>"
HTTP/1.1 201 Created
{
"username":"<USERNAME>",
"custom_id": "<CUSTOM_ID>",
"created_at": 1472604384000,
"id": "7f853474-7b70-439d-ad59-2481a0a9a904"
}
parameter | default | description |
---|---|---|
username semi-optional |
The username of the Consumer. Either this field or custom_id must be specified. |
|
custom_id semi-optional |
A custom identifier used to map the Consumer to another database. Either this field or username must be specified. |
A Consumer can have many credentials.
If you are also using the ACL plugin and whitelists with this service, you must add the new consumer to a whitelisted group. See ACL: Associating Consumers for details.
Create a Key
You can provision new credentials by making the following HTTP request:
$ curl -X POST http://kong:8001/consumers/{consumer}/key-auth -d ''
HTTP/1.1 201 Created
{
"consumer_id": "876bf719-8f18-4ce5-cc9f-5b5af6c36007",
"created_at": 1443371053000,
"id": "62a7d3b7-b995-49f9-c9c8-bac4d781fb59",
"key": "62eb165c070a41d5c1b58d9d3d725ca1"
}
consumer
: Theid
orusername
property of the Consumer entity to associate the credentials to.
form parameter | default | description |
---|---|---|
key optional |
You can optionally set your own unique key to authenticate the client. If missing, the plugin will generate one. |
Using the Key
Simply make a request with the key as a querystring parameter:
$ curl http://kong:8000/{proxy path}?apikey=<some_key>
Or in a header:
$ curl http://kong:8000/{proxy path} \
-H 'apikey: <some_key>'
Delete a Key
You can delete an API Key by making the following HTTP request:
$ curl -X DELETE http://kong:8001/consumers/{consumer}/key-auth/{id}
HTTP/1.1 204 No Content
consumer
: Theid
orusername
property of the Consumer entity to associate the credentials to.id
: Theid
attribute of the key credential object.
Upstream Headers
When a client has been authenticated, the plugin will append some headers to the request before proxying it to the upstream service, so that you can identify the Consumer in your code:
X-Consumer-ID
, the ID of the Consumer on KongX-Consumer-Custom-ID
, thecustom_id
of the Consumer (if set)X-Consumer-Username
, theusername
of the Consumer (if set)X-Credential-Username
, theusername
of the Credential (only if the consumer is not the ‘anonymous’ consumer)X-Anonymous-Consumer
, will be set totrue
when authentication failed, and the ‘anonymous’ consumer was set instead.
You can use this information on your side to implement additional logic. You can use the X-Consumer-ID
value to query the Kong Admin API and retrieve more information about the Consumer.
Paginate through keys
You can paginate through the API keys for all Consumers using the following request:
$ curl -X GET http://kong:8001/key-auths
{
"total":3,
"data":[
{
"id":"17ab4e95-9598-424f-a99a-ffa9f413a821",
"created_at":1507941267000,
"key":"Qslaip2ruiwcusuSUdhXPv4SORZrfj4L",
"consumer_id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
},
{
"id":"6cb76501-c970-4e12-97c6-3afbbba3b454",
"created_at":1507936652000,
"key":"nCztu5Jrz18YAWmkwOGJkQe9T8lB99l4",
"consumer_id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
},
{
"id":"b1d87b08-7eb6-4320-8069-efd85a4a8d89",
"created_at":1507941307000,
"key":"26WUW1VEsmwT1ORBFsJmLHZLDNAxh09l",
"consumer_id":"3c2c8fc1-7245-4fbb-b48b-e5947e1ce941"
}
]
}
You can filter the list using the following query parameters:
Attributes | Description |
---|---|
id optional |
A filter on the list based on the key-auth credential id field. |
key optional |
A filter on the list based on the key-auth credential key field. |
consumer_id optional |
A filter on the list based on the key-auth credential consumer_id field. |
size optional, default is 100 |
A limit on the number of objects to be returned. |
offset optional |
A cursor used for pagination. offset is an object identifier that defines a place in the list. |
Retrieve the Consumer associated with a key
It is possible to retrieve a Consumer associated with an API Key using the following request:
curl -X GET http://kong:8001/key-auths/{key or id}/consumer
{
"created_at":1507936639000,
"username":"foo",
"id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
}
key or id
: Theid
orkey
property of the API key for which to get the associated Consumer.