Key Auth

You are browsing documentation for an outdated plugin version.

Looking for the plugin's configuration parameters? You can find them in the Key Auth configuration reference doc.

This plugin lets you add API key authentication to a service or a route. Consumers then add their API key either in a query string parameter, a header, or a request body to authenticate their requests.

This plugin can be used for authentication in conjunction with the Application Registration plugin.

This plugin also comes in an enterprise version: Key Authentication Encrypted, which provides the ability to encrypt keys. Keys are encrypted at rest in the API gateway datastore.

Case sensitivity

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 are treated differently when searching the request header fields versus searching the query string. As a best practice, 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. To restrict usage to certain authenticated users, also add the ACL plugin (not covered here) and create allowed or denied groups of users.

Usage

Create a Consumer

You need to associate a credential to an existing Consumer object. A Consumer can have many credentials.

curl -d "username=user123&custom_id=SOME_CUSTOM_ID" http://localhost:8001/consumers/

consumers:
- username: user123
  custom_id: SOME_CUSTOM_ID

In both cases, the parameters are as described below:

If you are also using the ACL plugin and allow lists with this service, you must add the new Consumer to the allowed group. See ACL: Associating Consumers for details.

For more information about how to configure anonymous access, see Anonymous Access.

Multiple Authentication

Kong Gateway supports multiple authentication plugins for a given service, allowing different clients to use different authentication methods to access a given service or route. For more information, see Multiple Authentication.

Create a Key

Note: We recommend letting the API gateway autogenerate the key. Only specify it yourself if you are migrating an existing system to Kong Gateway. You must reuse your keys to make the migration to Kong Gateway transparent to your consumers.

curl -X POST http://localhost:8001/consumers/{USERNAME_OR_ID}/key-auth

HTTP/1.1 201 Created
{
  "key": "5SRmk6gLnTy1SyQ1Cl9GzoRXJbjYGGbZ",
  "created_at": 1655412883,
  "tags": null,
  "ttl": null,
  "id": "0103844a-0b40-42c8-aa71-64e98e2e525f",
  "consumer": {
    "id": "d9e37c7d-3261-4b7b-81a6-a94bc203a0ca"
  }
}

keyauth_credentials:
- consumer: {USERNAME_OR_ID}
  ttl: 5000
  tags:
    - example_tag
  key: example_apikey

In both cases, the fields/parameters work as follows:

Make a Request with the Key

Make a request with the key as a query string parameter:

curl http://localhost:8000/{proxy path}?apikey={some_key}

Note: The key_in_query plugin parameter must be set to true (default).

Make a request with the key in a header:

curl http://localhost:8000/{proxy path} \
    -H 'apikey: {some_key}'

Note: The key_in_header plugin parameter must be set to true (default).

Make a request with the key in the body:

curl http://localhost:8000/{proxy path} \
    --data 'apikey={some_key}'

Note: The key_in_body plugin parameter must be set to true (default is false).

gRPC clients are supported too:

grpcurl -H 'apikey: {some_key}' ...

About API Key Locations in a Request

Use cases for key locations:

• Recommended: Use key_in_header (enabled by default) as the most common and secure way to do service-to-service calls.
• If you need to share links to browser clients, use key_in_query (enabled by default). Note that query parameter requests can appear within application logs and URL browser bars, which expose the API key.
• If you are sending a form with a browser, such as a login form, use key_in_body. This option is set to false by default because it’s a less common use case, and is a more expensive and less performant HTTP request.

For better security, only enable the key locations that you need to use.

Disable a Key Location

This example disables using a key in a query parameter:

curl -X POST http://localhost:8001/routes/{NAME_OR_ID}/plugins \
    --data "name=key-auth"  \
    --data "config.key_names=apikey" \
    --data "config.key_in_query=false"

Delete a Key

Delete an API Key by making the following request:

curl -X DELETE http://localhost:8001/consumers/{USERNAME_OR_ID}/key-auth/{ID}

Response:

HTTP/1.1 204 No Content

• USERNAME_OR_ID: The id or username property of the Consumer entity to associate the credentials to.
• ID: The id attribute of the key credential object.

Upstream Headers

When a client has been authenticated, the plugin appends 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 in Kong.
• X-Consumer-Custom-ID: The custom_id of the consumer (if set).
• X-Consumer-Username: The username of the consumer (if set).
• X-Credential-Identifier: The identifier of the credential (only if the consumer is not the anonymous consumer).
• X-Anonymous-Consumer: Is set to true if authentication fails, and the anonymous consumer is 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

Paginate through the API keys for all Consumers by making the following request:

curl -X GET http://localhost:8001/key-auths

Response:

...
{
   "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" }
      }
   ]
   "next":null,
}

Filter the list by Consumer by using a different endpoint:

curl -X GET http://localhost:8001/consumers/{USERNAME_OR_ID}/key-auth

In the above, substitute the username or id property associated with the Consumer.

Response:

...
{
    "data": [
       {
         "id":"6cb76501-c970-4e12-97c6-3afbbba3b454",
         "created_at":1507936652000,
         "key":"nCztu5Jrz18YAWmkwOGJkQe9T8lB99l4",
         "consumer": { "id": "c0d92ba9-8306-482a-b60d-0cfdd2f0e880" }
       }
    ]
    "next":null,
}

Retrieve the Consumer associated with a key

Retrieve a Consumer associated with an API key by making the following request:

curl -X GET http://localhost:8001/key-auths/{KEY_OR_ID}/consumer

In the above, substitute either the key or id property associated with the key authentication entity.

Response:

{
   "created_at":1507936639000,
   "username":"foo",
   "id":"c0d92ba9-8306-482a-b60d-0cfdd2f0e880"
}

Request behavior matrix

The following table describes how Kong Gateway behaves in various scenarios: