<commit_before>[role="xpack"]
[[service-accounts]]
=== Service accounts

beta::[]

The {stack-security-features} provide _service accounts_ specifically for
integration with external services that connect to {es}, such as {fleet} server.
Service accounts have a fixed set of privileges and cannot be authenticated
until you create a service account token for them. Additionally, service
accounts are predefined in code, and are always enabled.

With service accounts, services (such as {fleet} server) can create a
service account token, authenticate with that token, and manage their own API keys.
Multiple service account tokens can be created for the same service account.
This prevents credential sharing between multiple instances of the same external service.
That is, these instances can assume the same identity while having their own distinct
service account tokens for authentication.

=== Service accounts vs built-in users
Service account is an evolution of the built-in users. It provides
flexibility over built-in users because they:

* Do not rely on the <<native-realm,internal `native` realm>>, and aren't
always required to rely on the `.security` index
* Use a role descriptor named after the service account principal instead of traditional roles
* Support multiple credentials through service account tokens

Service accounts are not included in the response of the
<<security-api-get-user,get users API>>. To retrieve a service account, use the
<<security-api-get-service-accounts,get service accounts API>>.

[[service-accounts-explanation]]
==== How service accounts work
Service accounts have a
<<security-api-get-service-accounts-path-params,unique principal>> that takes
the format of `<namespace>/<service>`, where the `namespace` is a top-level
grouping of service accounts, and `service` is the name of the service.

Currently, only one service account is available:

`elastic/fleet-server`:: The service account used by the {fleet} server to
communicate with {es}.

// tag::service-accounts-usage[]
IMPORTANT: The predefined service accounts are intended for external services
connecting to {es}. Do not attempt to use service accounts for authenticating
individual users.
// end::service-accounts-usage[]

// tag::service-accounts-tls[]
In <<dev-vs-prod-mode,production mode>>, service accounts require TLS on the
HTTP interface. A runtime check prevents you from invoking any related APIs or
authenticating with a service account token unless TLS is enabled on the HTTP
interface. See <<encrypt-http-communication,encrypt HTTP client communications for {es}>>.
// end::service-accounts-tls[]

[[service-accounts-tokens]]
==== How service account tokens work
A service account token, or simply service token,
is a unique string that a service uses to authenticate
with {es}. For a given service account, each token must have a unique name.
Because tokens include access credentials, they should always be kept secret
by whichever client is using them.

Service account tokens can be backed by either the `service_tokens` file or the
`.security` index. You can create multiple service account tokens for a single
service account, which enables multiple instances of the same service to run
with different credentials.

You must create a service account token to use a service account. You can
create a service account token using either:

* The <<service-tokens-command,elasticsearch-service-tokens>> CLI tool, which
saves the new service account token in the `$ES_HOME/config/service_tokens` file
and outputs the bearer token to your terminal
* The <<security-api-create-service-token,create service account tokens API>>,
which saves the new service account token in the `.security` index and returns
the bearer token in the HTTP response

Service account tokens never expire. You must actively <<security-api-delete-service-token,delete>> them if they are no longer needed.

[[authenticate-with-service-account-token]]
==== Authenticate with service account tokens

NOTE: Service accounts currently do not support basic authentication.

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 <KEY>" http://localhost:9200/_security/_authenticate
----
// NOTCONSOLE

A successful authentication response includes a `token` field, which contains a
`name` for the name of the service account token:

[source,js]
----
{
  "username": "elastic/fleet-server",
  "roles": [],
  "full_name": "Service account - elastic/fleet-server",
  "email": null,
  "token": {
    "name": "<PASSWORD>"      <1>
  },
  "metadata": {
    "_elastic_service_account": true
  },
  "enabled": true,
  "authentication_realm": {
    "name": "service_account",
    "type": "service_account"
  },
  "lookup_realm": {
    "name": "service_account",
    "type": "service_account"
  },
  "authentication_type": "token"
}
----
// NOTCONSOLE
<1> Name of the service account token
<commit_msg>[DOCS] Service account edits (#73732)<commit_after>[role="xpack"]
[[service-accounts]]
=== Service accounts

beta::[]

The {stack-security-features} provide _service accounts_ specifically for
integration with external services that connect to {es}, such as {fleet} server.
Service accounts have a fixed set of privileges and cannot authenticate
until you create a service account token for them. Additionally, service
accounts are predefined in code, and are always enabled.

A service account corresponds to a specific external service. You create service
account tokens for a service account. The service can then authenticate with the
token and perform relevant actions. For example, {fleet} server can use its
service token to authenticate with {es} and then manage its own API keys.

You can create multiple service tokens for the same service account, which
prevents credential sharing between multiple instances of the same
external service. Each instance can assume the same identity while using
their own distinct service token for authentication.

Service accounts provide flexibility over <<built-in-users,built-in users>> 
because they:

* Do not rely on the <<native-realm,internal `native` realm>>, and aren't
always required to rely on the `.security` index
* Use a role descriptor named after the service account principal instead of 
traditional roles
* Support multiple credentials through service account tokens

Service accounts are not included in the response of the
<<security-api-get-user,get users API>>. To retrieve a service account, use the
<<security-api-get-service-accounts,get service accounts API>>.

[discrete]
[[service-accounts-explanation]]
=== Service accounts usage
Service accounts have a
<<security-api-get-service-accounts-path-params,unique principal>> that takes
the format of `<namespace>/<service>`, where the `namespace` is a top-level
grouping of service accounts, and `service` is the name of the service and
must be unique within its namespace.

Service accounts are predefined in code. Currently, only one service account is available:

`elastic/fleet-server`:: The service account used by the {fleet} server to
communicate with {es}.

// tag::service-accounts-usage[]
IMPORTANT: Do not attempt to use service accounts for authenticating individual
users. Service accounts can only be authenticated with service tokens, which are
not applicable to regular users.
// end::service-accounts-usage[]

// tag::service-accounts-tls[]
In <<dev-vs-prod-mode,production mode>>, service accounts require TLS on the
HTTP interface. A runtime check prevents you from invoking any related APIs or
authenticating with a service account token unless TLS is enabled on the HTTP
interface. See <<encrypt-http-communication,encrypt HTTP client communications for {es}>>.
// end::service-accounts-tls[]

[discrete]
[[service-accounts-tokens]]
=== Service account tokens
A service account token, or service token, is a unique string that a
service uses to authenticate with {es}. For a given service account, each token
must have a unique name. Because tokens include access credentials, they should
always be kept secret by whichever client is using them.

Service tokens can be backed by either the `service_tokens` file or the
`.security` index. You can create multiple service tokens for a single
service account, which enables multiple instances of the same service to run
with different credentials.

You must create a service token to use a service account. You can
create a service token using either:

* The <<service-tokens-command,elasticsearch-service-tokens>> CLI tool, which
saves the new service token in the `$ES_HOME/config/service_tokens` file
and outputs the bearer token to your terminal
* The <<security-api-create-service-token,create service account token API>>,
which saves the new service token in the `.security` index and returns
the bearer token in the HTTP response

Both of these methods create a service token with a guaranteed secret string
length of `22`. The minimal, acceptable length of a secret string for a service
token is `10`. If the secret string doesn't meet this minimal length, 
authentication with {es} will fail without even checking the value of the
service token.

Service tokens never expire. You must actively 
<<security-api-delete-service-token,delete>> them if they are no longer needed.

[discrete]
[[authenticate-with-service-account-token]]
=== Authenticate with service tokens

NOTE: Service accounts currently do not support basic authentication.

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 AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TFdaSDZ" http://localhost:9200/_security/_authenticate
----
// NOTCONSOLE

A successful authentication response includes a `token` field, which contains a
`name` field for the name of the service token and a `type` field for the
type of the service token:

[source,js]
----
{
  "username": "elastic/fleet-server",
  "roles": [],
  "full_name": "Service account - elastic/fleet-server",
  "email": null,
  "token": {
    "name": "token1",                 <1>
    "type": "_service_account_index"  <2>
  },
  "metadata": {
    "_elastic_service_account": true
  },
  "enabled": true,
  "authentication_realm": {
    "name": "_service_account",
    "type": "_service_account"
  },
  "lookup_realm": {
    "name": "_service_account",
    "type": "_service_account"
  },
  "authentication_type": "token"
}
----
// NOTCONSOLE
<1> Name of the service account token.
<2> Type of service account token. The value always begins with
`_service_account_` and is followed by a string that indicates the service
token backend in use (can be either `file` or `index`).

{'fraction_non_alphanumeric': 0.08312528895053167, 'fraction_numerical': 0.0026814609338881184, 'mean_word_length': 4.821313240043057, 'pattern_counts': {'":': 33, '<': 53, '<?xml version=': 0, '>': 53, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3522361', 'n_tokens_mistral': 2834, 'n_tokens_neox': 2748, 'n_words': 1353}