elasticsearch/docs/reference/security/authentication/token-authentication-services.asciidoc

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