104 lines
3.7 KiB
Plaintext
104 lines
3.7 KiB
Plaintext
[role="xpack"]
|
|
[[api-keys]]
|
|
=== API Keys
|
|
|
|
|
|
API keys enable you to create secondary credentials so that you can send
|
|
requests on behalf of the user. Secondary credentials have
|
|
the same or lower access rights.
|
|
|
|
For example, if you extract data from an {es} cluster on a daily
|
|
basis, you might create an API key tied to your credentials,
|
|
configure it with minimum access,
|
|
and then put the API credentials into a cron job.
|
|
Or, you might create API keys to automate ingestion of new data from
|
|
remote sources, without a live user interaction.
|
|
|
|
You can create API keys from the {kib} Console. To view and invalidate
|
|
API keys, open the main menu, then click *Stack Management > API Keys*.
|
|
|
|
[role="screenshot"]
|
|
image:user/security/api-keys/images/api-keys.png["API Keys UI"]
|
|
|
|
[float]
|
|
[[api-keys-service]]
|
|
=== {es} API key service
|
|
|
|
The {es} API key service is automatically enabled when you configure
|
|
{ref}/configuring-tls.html#tls-http[TLS on the HTTP interface].
|
|
This ensures that clients are unable to send API keys in clear-text.
|
|
|
|
When HTTPS connections are not enabled between {kib} and {es},
|
|
you cannot create or manage API keys, and you get an error message.
|
|
For more information, see the
|
|
{ref}/security-api-create-api-key.html[{es} API key documentation],
|
|
or contact your system administrator.
|
|
|
|
[float]
|
|
[[api-keys-security-privileges]]
|
|
=== Security privileges
|
|
|
|
You must have the `manage_security`, `manage_api_key`, or the `manage_own_api_key`
|
|
cluster privileges to use API keys in {kib}. To manage roles, open the main menu, then click
|
|
*Stack Management > Roles*, or use the <<role-management-api, {kib} Role Management API>>.
|
|
|
|
|
|
[float]
|
|
[[create-api-key]]
|
|
=== Create an API key
|
|
You can {ref}/security-api-create-api-key.html[create an API key] from
|
|
the {kib} Console. This example shows how to create an API key
|
|
to authenticate to a <<api, Kibana API>>.
|
|
|
|
[source,js]
|
|
POST /_security/api_key
|
|
{
|
|
"name": "kibana_api_key"
|
|
}
|
|
|
|
This creates an API key with the
|
|
name `kibana_api_key`. API key
|
|
names must be globally unique.
|
|
An expiration date is optional and follows
|
|
{ref}/common-options.html#time-units[{es} time unit format].
|
|
When an expiration is not provided, the API key does not expire.
|
|
|
|
The response should look something like this:
|
|
|
|
[source,js]
|
|
{
|
|
"id" : "XFcbCnIBnbwqt2o79G4q",
|
|
"name" : "kibana_api_key",
|
|
"api_key" : "FD6P5UA4QCWlZZQhYF3YGw"
|
|
}
|
|
|
|
Now, you can use the API key to request {kib} roles. You'll need to send a request with a
|
|
`Authorization` header with a value having the prefix `ApiKey` followed by the credentials,
|
|
where credentials is the base64 encoding of `id` and `api_key` joined by a colon. For example:
|
|
|
|
[source,js]
|
|
curl --location --request GET 'http://localhost:5601/api/security/role' \
|
|
--header 'Content-Type: application/json;charset=UTF-8' \
|
|
--header 'kbn-xsrf: true' \
|
|
--header 'Authorization: ApiKey aVZlLUMzSUJuYndxdDJvN0k1bU46aGxlYUpNS2lTa2FKeVZua1FnY1VEdw==' \
|
|
|
|
[float]
|
|
[[view-api-keys]]
|
|
=== View and invalidate API keys
|
|
The *API Keys* feature in Kibana lists your API keys, including the name, date created,
|
|
and expiration date. If an API key expires, its status changes from `Active` to `Expired`.
|
|
|
|
If you have `manage_security` or `manage_api_key` permissions,
|
|
you can view the API keys of all users, and see which API key was
|
|
created by which user in which realm.
|
|
If you have only the `manage_own_api_key` permission, you see only a list of your own keys.
|
|
|
|
You can invalidate API keys individually or in bulk.
|
|
Invalidated keys are deleted in batch after seven days.
|
|
|
|
[role="screenshot"]
|
|
image:user/security/api-keys/images/api-key-invalidate.png["API Keys invalidate"]
|
|
|
|
You cannot modify an API key. If you need additional privileges,
|
|
you must create a new key with the desired configuration and invalidate the old key.
|