[DOCS] Add token based authn documentation (#55957)

x-pack/docs/en/security/authentication/index.asciidoc

@@ -2,6 +2,7 @@
 include::overview.asciidoc[]
 include::built-in-users.asciidoc[]
 include::internal-users.asciidoc[]
+include::token-authentication-services.asciidoc[]
 include::realms.asciidoc[]
 include::realm-chains.asciidoc[]
 include::active-directory-realm.asciidoc[]

x-pack/docs/en/security/authentication/overview.asciidoc

@@ -24,3 +24,9 @@ When {security-features} are enabled, depending on the realms you've configured,
 you must attach your user credentials to the requests sent to {es}. For example,
 when using realms that support usernames and passwords you can simply attach 
 {wikipedia}/Basic_access_authentication[basic auth] header to the requests.
+
+The {security-features} provide two services: the token service and the api key
+service. You can use these services to exchange the current authentication for
+a token or key. This token or key can then be used as credentials for
+authenticating new requests. These services are enabled by default when TLS/SSL
+is enabled for HTTP.

x-pack/docs/en/security/authentication/realms.asciidoc

@@ -2,10 +2,11 @@
 [[realms]]
 === Realms
 
-Authentication in the {stack} {security-features} is handled by one or more
-authentication services called _realms_. A _realm_ is used to resolve and
-authenticate users based on authentication tokens. The {security-features}
-provide the following built-in realms:
+The {stack-security-features} authenticate users by using realms and one or more
+<<token-authentication-services,token-based authentication services>>.
+
+A _realm_ is used to resolve and authenticate users based on authentication
+tokens. The {security-features} provide the following built-in realms:
 
 _native_::
 An internal realm where users are stored in a dedicated {es} index.

x-pack/docs/en/security/authentication/token-authentication-services.asciidoc

@@ -0,0 +1,58 @@
+[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
+authentication and for the management of tokens. These tokens can be used as
+credentials attached to requests that are sent to {es}. When {es} receives a request
+that must be authenticated, it consults first the token-based authentication
+services 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:
+
+_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 dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvbmx5IHRlc3QgZGF0YS4gZG8gbm90IHRyeSB0byByZWFkIHRva2VuIQ==" http://localhost:9200/_cluster/health
+--------------------------------------------------
+// NOTCONSOLE
+--
+
+_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 VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==" 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>>.