Key Authentication - Encrypted

The Key Authentication Encrypted plugin adds encrypted API key authentication to a Gateway Service or Route.
Consumers can authenticate by including their API key in a query string, header, or request body.

This plugin extends the functionality of the Key Authentication plugin by allowing API keys to be stored in encrypted form within the Kong Gateway datastore.

Important: Before configuring this plugin, you must enable Kong Gateway’s encryption Keyring.

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

When you create a Consumer, you can specify a key with keyauth_credentials (declarative configuration) or the /consumers/{usernameOrId}/key-auth-enc endpoint.

When authenticating, Consumers must specify their key in either the query, body, or header:

curl http://localhost:8000/$PROXY_PATH?apikey=$APIKEY

curl http://localhost:8000/$PROXY_PATH \
--data 'apikey: {some_key}'

curl http://kong:8000/$PROXY_PATH \
-H 'apikey: $APIKEY'

API key locations in a request

Use the following recommendations for each key location:

• Recommended: Use config.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 config.key_in_query (enabled by default). Be aware 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 config.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 request.

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

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 Gateway follows these specifications as designed, meaning that the config.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 config.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 or Route. To restrict usage to certain authenticated users, add the ACL plugin and create allowed or denied groups of users.

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 Gateway.
• 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 Admin API and retrieve more information about the Consumer.