[DOCS] Service account edits (#73732)

* Put all service accounts information on one page

* De-emphasize connection with built-in accounts + edits

* Iterate on the docs: tweak, correction and more details.

* fix test

* Edits and minor text changes

Co-authored-by: Yang Wang <yang.wang@elastic.co>
Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>

x-pack/docs/en/security/authentication/service-accounts.asciidoc

@@ -6,46 +6,51 @@ 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
+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.
 
-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.
+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.
 
-=== 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:
+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
+* 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]]
-==== How service accounts work
+=== 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.
+grouping of service accounts, and `service` is the name of the service and
+must be unique within its namespace.
 
-Currently, only one service account is available:
+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: The predefined service accounts are intended for external services
-connecting to {es}. Do not attempt to use service accounts for authenticating
-individual users.
+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[]
@@ -55,33 +60,41 @@ 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]]
-==== 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 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 account token to use a service account. You can
-create a service account token using either:
+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 account token in the `$ES_HOME/config/service_tokens` file
+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 tokens API>>,
-which saves the new service account token in the `.security` index and returns
+* 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
 
-Service account tokens never expire. You must actively <<security-api-delete-service-token,delete>> them if they are no longer needed.
+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 account tokens
+=== Authenticate with service tokens
 
 NOTE: Service accounts currently do not support basic authentication.
 
@@ -95,7 +108,8 @@ curl -H "Authorization: Bearer AAEAAWVsYXN0aWM...vZmxlZXQtc2VydmVyL3Rva2VuMTo3TF
 // NOTCONSOLE
 
 A successful authentication response includes a `token` field, which contains a
-`name` for the name of the service account token:
+`name` field for the name of the service token and a `type` field for the
+type of the service token:
 
 [source,js]
 ----
@@ -105,22 +119,26 @@ A successful authentication response includes a `token` field, which contains a
   "full_name": "Service account - elastic/fleet-server",
   "email": null,
   "token": {
-    "name": "token1"      <1>
+    "name": "token1",                 <1>
+    "type": "_service_account_index"  <2>
   },
   "metadata": {
     "_elastic_service_account": true
   },
   "enabled": true,
   "authentication_realm": {
-    "name": "service_account",
-    "type": "service_account"
+    "name": "_service_account",
+    "type": "_service_account"
   },
   "lookup_realm": {
-    "name": "service_account",
-    "type": "service_account"
+    "name": "_service_account",
+    "type": "_service_account"
   },
   "authentication_type": "token"
 }
 ----
 // NOTCONSOLE
-<1> Name of the service account token
+<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`).