Key Auth

The Key Authentication plugin lets you add API key authentication to a Gateway Service or a Route. Consumers then add their key either in a query string parameter, a header, or a request body to authenticate their requests.

The advanced version of this plugin, Key Authentication Encrypted, provides the ability to encrypt keys. Keys are encrypted at rest in the Kong Gateway data store.

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

You can authenticate centrally-managed Consumers in Konnect by configuring the config.identity_realms field. See Realms for external Consumers in Konnect for an example configuration.

Identity realms are scoped to the Control Plane by default (scope: cp). The order in which you configure the identity realm dictates the priority in which the Data Plane attempts to authenticate the provided API keys: