Key Authentication - Encrypted

You are browsing unreleased documentation.

This plugin is not compatible with Konnect

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

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

This plugin provides more functionality than the open-source Key Authentication plugin, letting you store API keys in an encrypted format within the API gateway datastore.

Note: Before configuring this plugin, you must enable Kong Gateway’s encryption keyring. See the keyring getting started guide for more details.

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 -i -X POST http://localhost:8001/consumers/ \
  --data "username=example_user" \
  --data "custom_id=SOME_CUSTOM_ID"

consumers:
- username: example_user
  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.

Create a key

Note: We recommend that Kong Gateway auto generates 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-enc

HTTP/1.1 201 Created
{
    "consumer":
       {
           "id": "876bf719-8f18-4ce5-cc9f-5b5af6c36007"
           },
    "created_at": 1443371053000,
    "id": "62a7d3b7-b995-49f9-c9c8-bac4d781fb59",
    "key": "62eb165c070a41d5c1b58d9d3d725ca1",
}

curl -X POST http://localhost:8001/consumers/{USERNAME_OR_ID}/key-auth-enc
  --data "key=myapikey"

HTTP/1.1 201 Created
{
    "consumer": {
      "id": "876bf719-8f18-4ce5-cc9f-5b5af6c36007"
    },
    "created_at": 1443371053000,
    "id": "62a7d3b7-b995-49f9-c9c8-bac4d781fb59",
    "key": "myapikey",
}

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

The fields/parameters work as follows:

Make a request with the key

Key in query

To use the key in URL queries, set the configuration parameter key_in_query to true (default option).

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

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

Key in body

To use the key in a request body, set the configuration parameter key_in_body to true. The default value is false.

Make a request with the key in the body:

curl http://kong:8000/{proxy path} \
  --data 'apikey: <some_key>'

Key in header

To use the key in a request body, set the configuration parameter key_in_header to true (default option).

Make a request with the key in a header:

curl http://kong:8000/{proxy path} \
  -H 'apikey: <some_key>'

You can also use this option with a gRPC client:

grpcurl -H 'apikey: <some_key>' ...

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/{route}/plugins \
    --data "name=key-auth-enc"  \
    --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-enc/{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 using the following request:

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

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-enc

{USERNAME_OR_ID}: The username or ID of the consumer whose credentials need to be listed.

Response:

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

{USERNAME_OR_ID}: The username or ID of the consumer whose credentials need to be listed.

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-enc/{key_id}/consumer

key_id: The id property of the API key for the associated consumer.

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