mirror of
https://github.com/elastic/elasticsearch.git
synced 2025-04-25 15:47:23 -04:00
255c9a7f95
**Problem:** For historical reasons, source files for the Elasticsearch Guide's security, watcher, and Logstash API docs are housed in the `x-pack/docs` directory. This can confuse new contributors who expect Elasticsearch Guide docs to be located in `docs/reference`. **Solution:** - Move the security, watcher, and Logstash API doc source files to the `docs/reference` directory - Update doc snippet tests to use security Rel: https://github.com/elastic/platform-docs-team/issues/208
86 lines
3.8 KiB
Text
86 lines
3.8 KiB
Text
[role="xpack"]
|
|
[[token-authentication-services]]
|
|
=== Token-based authentication services
|
|
|
|
The {stack-security-features} authenticate users by using realms and one or
|
|
more token-based authentication services. The token-based authentication
|
|
services are used for authenticating and managing tokens. You can attach these
|
|
tokens to requests that are sent to {es} and use them as credentials. When {es}
|
|
receives a request that must be authenticated, it consults the token-based
|
|
authentication services first, and then the realm chain.
|
|
|
|
The {security-features} provide the following built-in token-based
|
|
authentication services, which are listed in the order they are consulted:
|
|
|
|
_service-accounts_::
|
|
+
|
|
--
|
|
|
|
The <<service-accounts,service accounts>> use either the
|
|
<<security-api-create-service-token,create service account token API>>
|
|
or the <<service-tokens-command,elasticsearch-service-tokens>> CLI tool to
|
|
generate service account tokens.
|
|
|
|
To use a service account token, include the generated token value in a request
|
|
with an `Authorization: Bearer` header:
|
|
|
|
[source,shell]
|
|
----
|
|
curl -H "Authorization: Bearer AAEAAWVsYXN0aWMvZ...mXQtc2VydmMTpyNXdkYmRib1FTZTl2R09Ld2FKR0F3" http://localhost:9200/_cluster/health
|
|
----
|
|
// NOTCONSOLE
|
|
|
|
include::service-accounts.asciidoc[tag=service-accounts-usage]
|
|
--
|
|
|
|
[[token-authentication-access-token]]
|
|
_token-service_::
|
|
The token service uses the <<security-api-get-token,get token API>> to
|
|
generate access tokens and refresh tokens based on the OAuth2 specification.
|
|
The access token is a short-lived token. By default, it expires after 20 minutes
|
|
but it can be configured to last a maximum of 1 hour. It can be refreshed by
|
|
using a refresh token, which has a lifetime of 24 hours. The access token is a
|
|
bearer token. You can use it by sending a request with an `Authorization`
|
|
header with a value that has the prefix "Bearer " followed by the value of the
|
|
access token. For example:
|
|
+
|
|
--
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
curl -H "Authorization: Bearer dGhpcyBpcyBub3Qx5...F0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
--
|
|
|
|
[[token-authentication-api-key]]
|
|
_api-key-service_::
|
|
The API key service uses the
|
|
<<security-api-create-api-key,create API key API>> to generate API keys.
|
|
By default, the API keys do not expire. When you make a request to create API
|
|
keys, you can specify an expiration and permissions for the API key. The
|
|
permissions are limited by the authenticated user's permissions. You can use the
|
|
API key by sending a request with an `Authorization` header with a value that
|
|
has the prefix "ApiKey " followed by the credentials. The credentials are the
|
|
base64 encoding of the API key ID and the API key joined by a colon. For example:
|
|
+
|
|
--
|
|
[source,shell]
|
|
--------------------------------------------------
|
|
curl -H "Authorization: ApiKey VnVhQ2ZHY0JDZGJrU...W0tZTVhT3g6dWkybHAyYXhUTm1zeWFrd0dk5udw==" http://localhost:9200/_cluster/health
|
|
--------------------------------------------------
|
|
// NOTCONSOLE
|
|
--
|
|
|
|
Depending on your use case, you may want to decide on the lifetime of the tokens
|
|
generated by these services. You can then use this information to decide which
|
|
service to use to generate and manage the tokens. Non-expiring API keys may seem
|
|
like the easy option but you must consider the security implications that come
|
|
with non-expiring keys. Both the _token-service_ and _api-key-service_ permit
|
|
you to invalidate the tokens. See
|
|
<<security-api-invalidate-token,invalidate token API>> and
|
|
<<security-api-invalidate-api-key,invalidate API key API>>.
|
|
|
|
IMPORTANT: Authentication support for JWT bearer tokens was introduced in {es}
|
|
8.2 through the <<jwt-auth-realm>>, which cannot be enabled through
|
|
token-authentication services. Realms offer flexible order and configurations of
|
|
zero, one, or multiple JWT realms.
|