このページは、まだ日本語ではご利用いただけません。翻訳中です。
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.
In both cases, the parameters are as described below:
parameter | 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. |
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.
The fields/parameters work as follows:
Field/parameter | Description |
---|---|
{consumer} |
The id or username property of the consumer entity to associate the credentials to. |
tags optional |
You can optionally assign a list of tags to your key . |
key optional |
You can optionally set your own unique key to authenticate the client. If missing, the plugin will generate one. |
ttl optional |
The number of seconds the key is going to be valid. If missing or set to zero, the ttl of the key is unlimited. If present, the value must be an integer between 0 and 100000000 . Currently, it is incompatible with DB-less mode or Hybrid mode. |
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
キーの場所のユースケース
- 推奨:サービス間呼び出しを実行する最も一般的で安全な方法として、
key_in_header
(デフォルトで有効)を使用します。 - ブラウザクライアントにリンクを共有する必要がある場合は、
key_in_query
を使用します(デフォルトで有効になっています)。 クエリパラメータのリクエストは、アプリケーションログやURLブラウザバーに表示される可能性があり、これによってAPIキーが公開されることに注意してください。 - ログインフォームなど、ブラウザでフォームを送信する場合は、
key_in_body
を使用します。このオプションは、あまり一般的ではないユースケースであり、コストが高くパフォーマンスの低いHTTPリクエストであるため、デフォルトでfalse
に設定されています。
セキュリティを強化するために、使用する必要のあるキーの場所のみを有効にします。
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}
: 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 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
: Thecustom_id
of the consumer (if set). -
X-Consumer-Username
: Theusername
of the consumer (if set). -
X-Credential-Identifier
: The identifier of the credential (only if the consumer is not theanonymous
consumer). -
X-Anonymous-Consumer
: Is set totrue
if authentication fails, and theanonymous
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"
}